致谢

Acknowledgments

只有当你感谢所有为你的书出版过程做出贡献的人时，你才会意识到有多少人参与其中。没有其他人的慷慨、耐心和洞察力，这样的工作就不会发生，如果没有挑战、测试和返工，它也不会成功。它依赖于那些足够善良（有时是在不知不觉中！）参与这些活动的人，就像它依赖于作者一样，我对这些人的善良和智慧感激不尽。

It is only when you come to thank all those who have contributed to the process of getting your book released that you realize just how many people have been involved. A work like this doesn’t happen without the generosity, patience and insight of others, nor does it succeed without being challenged, tested and reworked. It relies on those who were kind enough to (sometimes unknowingly!) get involved in these activities as much as it does on the author and I cannot thank these people enough for their kindness and wisdom.

如果没有 Kitware 及其员工过去和现在的持续支持，CMake 社区不会像今天这样强大和充满活力。我想特别提及 CMake 项目负责人 Brad King，他通过包容和鼓励的方式来处理新的 CMake 贡献者，让像我这样的人非常受欢迎，并感到有能力参与其中。通过观察他与开发人员和用户互动的方式、提供强有力的领导力并营造尊重他人的环境，我个人从他身上学到了很多东西。不言而喻，多年来 CMake 的许多贡献者的努力也值得赞扬，他们的努力通常是纯粹自愿的。我对这么多人所做的贡献以及对软件开发世界的积极影响感到谦卑。

The CMake community wouldn’t be as strong and as vibrant as it is today without the ongoing support of Kitware and its staff, both past and present. I’d like to make special mention of Brad King, the CMake project leader, who through his inclusive and encouraging approach to handling new CMake contributors has made people like myself very welcome and feel empowered to get involved. I have personally learned much from him just by observing the way he interacts with developers and users, providing strong leadership and fostering an environment of respect for others. It also goes without saying that the many contributors to CMake over the years also deserve much praise for their efforts, often made on a purely voluntary basis. I’m humbled by the scale of contributions that have been made by so many and by the positive impact on the world of software development.

许多人慷慨地同意审阅本书中的材料，如果没有他们，技术准确性和可读性都会受到影响。任何剩余的错误和缺陷都是我自己的。CMake 开发人员 Gregor Jasny 和 Christian Pfeiffer 在第一份出版物的整个审核过程中做出了宝贵的贡献。我衷心感谢他们的建议和见解。还要感谢尼尔斯·格拉迪茨 (Nils Gladitz) 的投入，特别是在第一份出版物发布之前的短时间内。我还要感谢我以前的同事马特·博尔格 (Matt Bolger) 和拉克兰·赫瑟顿 (Lachlan Hetherton)，他们都提供了建设性的反馈，并提醒我以新的眼光看待问题的重要性。

A number of people generously agreed to review the material in this book, without whom both technical accuracy and readability would have suffered. Any remaining errors and deficiencies are squarely my own. Fellow CMake developers Gregor Jasny and Christian Pfeiffer were valuable contributors throughout the review process for the first publication. I am truly grateful for their suggestions and insights. Thanks also to Nils Gladitz for his input, especially at such short notice before the first publication. I’d also like to thank my past colleagues, Matt Bolger and Lachlan Hetherton, both of whom provided constructive feedback and reminded me of the importance of a fresh set of eyes.

许多人慷慨地审阅了后续版本的章节。其中许多人也是 CMake 的贡献者或维护者，我很感谢他们花时间审阅本书并改进 CMake 本身。感谢 Cristian Adam 审阅了第 30 章“构建性能”和 第 31 章“使用 Qt”，并感谢 Tobias Hunger、Alexandru Croitor、Joerg Bornemann、Sebastian Holtermann 和 Burkhard Stubert，他们都在不同阶段审阅了有关 Qt 的材料。Alex Turbov 和 Marc Chevrier 还为第七版中的新增和更新材料提供了宝贵的意见和建议。

A number of people have generously reviewed chapters for subsequent editions. Many of these people are also CMake contributors or maintainers, and I am grateful for both their time reviewing this book and in improving CMake itself. Thanks to Cristian Adam for reviewing Chapter 30, Build Performance and Chapter 31, Working With Qt, and to Tobias Hunger, Alexandru Croitor, Joerg Bornemann, Sebastian Holtermann and Burkhard Stubert, all of whom also reviewed the material on Qt at various stages. Alex Turbov and Marc Chevrier also provided valuable comments and suggestions for new and updated material in the 7th edition.

我们也非常感谢读者提供的有用反馈。我想特别提及 Declan Moran 和 Ganesh A. Hegde 的努力，他们都强调了一些改进和修正。

The helpful feedback received from readers is also much appreciated. I’d like to make particular mention of the efforts of Declan Moran and Ganesh A. Hegde, both of whom highlighted a number of improvements and corrections.

特别值得一提的是我过去的同事迈克·韦克(Mike Wake)。本书中的大部分内容都是在真实的、积极开发的生产项目中经过反复推敲和测试的。关于如何从可用性和稳健性角度改进事物，已经出现了错误的转折和许多技术讨论。他为解决这些问题提供空间和鼓励，以及他愿意忍受一些短期（有时不是那么短期）的痛苦，这些都是将许多流程和技术提炼为有效的方法的重要组成部分。实践。我也非常感谢在一些压力更大、筋疲力尽的时期，在正确的时间及时提供的建议和鼓励。

A special mention is deserved for my past colleague Mike Wake. Much of the material in this book was thrashed out and tested in real, actively developed production projects. There have been wrong turns and many technical discussions on how to improve things from both a usability and robustness perspective. His support in giving the space and encouragement to work through these things and his willingness to wear some short-term (and sometimes not-so-short-term) pain have been an instrumental part of distilling many processes and techniques down to what works in practice. I am also very grateful for the timely words of advice and encouragement delivered at just the right time during some of the more stressful and exhausting periods.

我还要向 Asciidoctor（用于编译和准备本书的软件）背后的人员表示感谢。尽管这些材料的规模、复杂性和技术性质，我一直惊讶于它如何使自助出版不仅成为一种可行的选择，而且成为一种令人愉快的体验，而且几乎没有实际限制。现在从作者到读者的路径比我最初开始写这本书时要短得多、简单得多。感谢您提供这么棒的工具！

I would also like to express my gratitude to the people behind Asciidoctor, the software used to compile and prepare this book. Despite the size, complexity and technical nature of the material, I have been constantly amazed at how it has made self-publishing not just a viable option, but also an enjoyable experience with surprisingly few practical limitations. The path from author to reader is now so much shorter and simpler than when I initially began work on this book. Thanks for the awesome tool!

这本书的封面和网站上的一些支持材料是我对图形设计比我更好的眼光和理解的结果。对于我的朋友兼设计师 V，你以某种方式设法理解我随机的、互不相关的想法和相互冲突的片段的方式仍然让我感到困惑。我不明白你是怎么做到的，但我很喜欢最终的结果！

The book’s cover and some of the supporting material on the website are the result of a better eye and understanding of graphical design than my own. To my friend and designer, V, the way you somehow managed to make sense of my random, disconnected ideas and conflicting snippets still baffles me. I don’t understand how you do it, but I do like the end result!

在每本书的致谢部分，作者总是感谢家人和配偶，这是有充分理由的。你需要付出巨大的理解和牺牲来忍受你的疲劳，你无法做很多普通人可以做的事情，以及你在一个项目上投入比他们更多的时间的不合理决定。我真的无法表达对我妻子的感激之情，她在本书的写作、出版和定期更新的整个过程中给予了我如此支持和耐心。我确实是一个非常幸运的人。

In every book’s acknowledgments section, the author invariably thanks family members and spouses, and there’s good reason for that. It takes a huge amount of understanding and sacrifice to tolerate your tiredness, your unavailability to do many of the things ordinary people get to do and your unreasonable decision to devote more time to a project than to them. I truly cannot express the depth of my gratitude to my wife for the way she has managed to be so supportive and patient throughout the process of getting this book written, published and regularly updated. I am indeed a very fortunate human being.

2.1. 源内构建

2.1. In-source Builds

尽管不鼓励，但源目录和构建目录可以相同。这种安排称为源内构建。开发人员在职业生涯初期通常会开始使用这种方法，因为这种方法被认为很简单。然而，源内构建的主要困难是所有构建输出都与源文件混合在一起。这种缺乏分离的情况会导致目录中充斥着各种文件和子目录，从而使管理项目源变得更加困难，并面临构建输出覆盖源文件的风险。它还使得使用版本控制系统变得更加困难，因为构建创建了许多文件，源代码控制工具必须知道要忽略这些文件，或者开发人员必须在提交期间手动排除这些文件。源内构建的另一个缺点是清除所有构建输出并使用干净的源代码树重新开始可能并不简单。由于这些原因，开发人员不鼓励尽可能使用源内构建，即使对于简单的项目也是如此。

It is possible, though discouraged, for the source and build directories to be the same. This arrangement is called an in-source build. Developers at the beginning of their career often start out using this approach because of the perceived simplicity. The main difficulty with in-source builds, however, is that all the build outputs are intermixed with the source files. This lack of separation causes directories to become cluttered with all sorts of files and subdirectories, making it harder to manage the project sources and running the risk of build outputs overwriting source files. It also makes working with version control systems more difficult, since there are lots of files created by the build which either the source control tool has to know to ignore or the developer has to manually exclude during commits. One other drawback to in-source builds is that it can be non-trivial to clear out all build output and start again with a clean source tree. For these reasons, developers are discouraged from using in-source builds where possible, even for simple projects.

2.2. 外源构建

2.2. Out-of-source Builds

更可取的安排是源目录和构建目录不同，这称为源外构建。这使源和构建输出彼此完全分离，从而避免了源内构建遇到的混合问题。源外构建还有一个优点，即开发人员可以为同一源目录创建多个构建目录，这允许使用不同的选项集设置构建，例如调试和发布版本等。

The more preferable arrangement is for the source and build directories to be different, which is called an out-of-source build. This keeps the sources and the build outputs completely separate from each other, thus avoiding the intermixing problems experienced with in-source builds. Out-of-source builds also have the advantage that the developer can create multiple build directories for the same source directory, which allows builds to be set up with different sets of options, such as debug and release versions, etc.

本书将始终使用源代码外构建，并将遵循源目录和构建目录位于共同父目录下的模式。构建目录将被称为build或其某种变体。例如：

This book will always use out-of-source builds and will follow the pattern of the source and build directories being under a common parent. The build directory will be called build, or some variation thereof. For example:

一些开发人员使用的一种变体是使构建目录成为源目录的子目录。这提供了源外构建的大部分优点，但它仍然带有源内安排的一些缺点。除非有充分的理由以这种方式构建事物，否则建议将构建目录完全保留在源代码树之外。

A variation on this used by some developers is to make the build directory a subdirectory of the source directory. This offers most of the advantages of an out-of-source build, but it does still carry with it some of the disadvantages of an in-source arrangement. Unless there is a good reason to structure things that way, keeping the build directory completely outside of the source tree instead is recommended.

2.3. 生成项目文件

2.3. Generating Project Files

选择目录结构后，开发人员运行 CMake，它读取文件CMakeLists.txt并在构建目录中创建项目文件。开发人员通过选择特定的项目文件生成器来选择要创建的项目文件的类型。支持一系列不同的生成器，下表列出了更常用的生成器。

Once the choice of directory structure has been made, the developer runs CMake, which reads in the CMakeLists.txt file and creates project files in the build directory. The developer selects the type of project file to be created by choosing a particular project file generator. A range of different generators are supported, with the more commonly used ones listed in the table below.

一些生成器生成支持多种配置的项目（例如调试、发布等）。这些允许开发人员在不同的构建配置之间进行选择，而无需重新运行 CMake，这更适合生成器创建在 Xcode 和 Visual Studio 等 IDE 环境中使用的项目。对于不支持多种配置的生成器，开发人员必须重新运行 CMake 以在调试、发布等之间切换构建。这些更简单，并且通常在与特定编译器（Qt Creator）关系不密切的 IDE 环境中具有良好的支持、KDevelop 等）。

Some of the generators produce projects which support multiple configurations (e.g. Debug, Release, etc.). These allow the developer to choose between different build configurations without having to re-run CMake, which is more suitable for generators creating projects for use in IDE environments like Xcode and Visual Studio. For generators which do not support multiple configurations, the developer has to re-run CMake to switch the build between Debug, Release, etc. These are simpler and often have good support in IDE environments not so closely associated with a particular compiler (Qt Creator, KDevelop, etc.).

运行 CMake 的最基本方法是通过cmake命令行实用程序。调用它的最简单方法是更改​​到构建目录并将选项传递给cmake生成器类型和源树的位置。例如：

The most basic way to run CMake is via the cmake command line utility. The simplest way to invoke it is to change to the build directory and pass options to cmake for the generator type and location of the source tree. For example:

mkdir 构建
光盘构建
cmake -G "Unix Makefiles" ../source

mkdir build
cd build
cmake -G "Unix Makefiles" ../source

如果-G省略该选项，CMake 将根据主机平台选择默认生成器类型。如果使用 CMake 3.15 或更高版本，可以通过将环境变量设置为所需的默认值来覆盖此默认值 CMAKE_GENERATOR。对于所有生成器类型，CMake 将执行一系列测试以确定如何设置项目文件。这包括验证编译器是否正常工作、确定支持的编译器功能集以及各种其他任务等。成功后，CMake 完成之前将记录各种信息，如下所示：

If the -G option is omitted, CMake will choose a default generator type based on the host platform. If using CMake 3.15 or later, this default can be overridden by setting the CMAKE_GENERATOR environment variable to the desired default instead. For all generator types, CMake will carry out a series of tests to determine how to set up the project files. This includes things like verifying that the compilers work, determining the set of supported compiler features and various other tasks. A variety of information will be logged before CMake finishes with lines like the following upon success:

-- 配置完成
-- 生成完成
-- 构建文件已写入：/some/path/build

-- Configuring done
-- Generating done
-- Build files have been written to: /some/path/build

上面强调了项目文件的创建实际上涉及两个步骤；配置和生成。在配置阶段，CMake 读取文件 CMakeLists.txt并构建整个项目的内部表示。完成此操作后，生成阶段将创建项目文件。配置和生成之间的区别对于基本的 CMake 使用来说并不那么重要，但在后面的章节中，配置和生成的分离变得很重要。第 10 章“生成器表达式”对此进行了更详细的介绍 。

The above highlights that project file creation actually involves two steps; configuring and generating. During the configuring phase, CMake reads in the CMakeLists.txt file and builds up an internal representation of the entire project. After this is done, the generation phase creates the project files. The distinction between configuring and generating doesn’t matter so much for basic CMake usage, but in later chapters the separation of configuration and generation becomes important. This is covered in more detail in Chapter 10, Generator Expressions.

当 CMake 完成运行时，它将CMakeCache.txt在构建目录中保存一个文件。CMake 使用此文件保存详细信息，以便再次运行时可以重用第一次计算的信息并加快项目生成速度。正如后面章节中所介绍的，它还允许在运行之间保存开发人员选项。GUI 应用程序cmake-gui可以作为运行cmake命令行工具的替代方法，但 GUI 应用程序的介绍推迟到第 5 章“变量” ，其中它的用处更加明显。

When CMake has completed its run, it will have saved a CMakeCache.txt file in the build directory. CMake uses this file to save details so that if it is run again, it can re-use information computed the first time and speed up the project generation. As covered in later chapters, it also allows developer options to be saved between runs. A GUI application, cmake-gui, is available as an alternative to running the cmake command line tool, but the introduction of the GUI application is deferred to Chapter 5, Variables where its usefulness is more clearly evident.

2.4. 运行构建工具

2.4. Running The Build Tool

此时，项目文件现已可用，开发人员可以按照他们习惯的方式使用他们选择的构建工具。构建目录将包含必要的项目文件，这些文件可以加载到 IDE 中、通过命令行工具读取等。或者，cmake可以代表开发人员调用构建工具，如下所示：

At this point, with project files now available, the developer can use their selected build tool in the way to which they are accustomed. The build directory will contain the necessary project files which can be loaded into an IDE, read by command line tools, etc. Alternatively, cmake can invoke the build tool on the developer’s behalf like so:

cmake --build /pathTo/build --config 调试 --target MyApp

cmake --build /pathTo/build --config Debug --target MyApp

即使对于开发人员可能更习惯通过 Xcode 或 Visual Studio 等 IDE 使用的项目类型，这也适用。该--build选项指向 CMake 项目生成步骤使用的构建目录。对于多配置生成器，该--config选项指定要构建的配置，而单配置生成器将忽略该--config 选项并依赖于执行 CMake 项目生成步骤时提供的信息。第 14 章“构建类型”中详细介绍了指定构建配置。该--target选项可用于告诉构建工具要构建什么，或者如果省略，将构建默认目标。使用 CMake 3.15 或更高版本，可以在选项后列出多个目标--target ，并用空格分隔。

This works even for project types the developer may be more accustomed to using through an IDE like Xcode or Visual Studio. The --build option points to the build directory used by the CMake project generation step. For multi configuration generators, the --config option specifies which configuration to build, whereas single configuration generators will ignore the --config option and rely instead on information provided when the CMake project generation step was performed. Specifying the build configuration is covered in depth in Chapter 14, Build Type. The --target option can be used to tell the build tool what to build, or if omitted, the default target will be built. With CMake 3.15 or later, multiple targets can be listed after the --target option, separated by spaces.

虽然开发人员通常会在日常开发中直接调用他们选择的构建工具，但通过cmake如上所示的命令调用它在驱动自动构建的脚本中可能更有用。使用这种方法，一个简单的脚本化构建可能看起来像这样：

While developers will typically invoke their selected build tool directly in day-to-day development, invoking it via the cmake command as shown above can be more useful in scripts driving an automated build. Using this approach, a simple scripted build might look something like this:

mkdir 构建
光盘构建
cmake -G "Unix Makefiles" ../source
cmake --build 。--config 发布 --target MyApp

mkdir build
cd build
cmake -G "Unix Makefiles" ../source
cmake --build . --config Release --target MyApp

如果开发人员希望尝试不同的生成器，所需要做的就是更改-GCMake 选项的参数，然后将自动调用正确的构建工具。构建工具甚至不必在用户上即可PATH工作（尽管它可能需要在首次调用cmake --build时用于初始配置步骤）。cmake

If the developer wishes to experiment with different generators, all that needs to be done is change the argument given to the -G CMake option and the correct build tool will be automatically invoked. The build tool doesn’t even have to be on the user’s PATH for cmake --build to work (although it may need to be for the initial configuration step when cmake is first invoked).

2.5. 推荐做法

2.5. Recommended Practices

即使第一次开始使用 CMake，也建议养成将构建目录与源代码树完全分开的习惯。尽早体验这种安排的好处的一个好方法是为同一源目录设置两个或多个不同的构建。一个构建可以配置调试设置，另一个构建可以配置发布构建。另一种选择是为不同的构建目录使用不同的项目生成器，例如 Unix Makefiles 和 Xcode。这可以帮助捕获对特定构建工具的任何意外依赖性，或检查生成器类型之间不同的编译器设置。

Even when first starting out using CMake, it is advisable to make a habit of keeping the build directory completely separate from the source tree. A good way to get early experience of the benefits of such an arrangement is to set up two or more different builds for the same source directory. One build could be configured with Debug settings, the other for a Release build. Another option is to use different project generators for the different build directories, such as Unix Makefiles and Xcode. This can help to catch any unintended dependencies on a particular build tool or to check for differing compiler settings between generator types.

在项目的早期阶段专注于使用一种特定类型的项目生成器可能很诱人，特别是如果开发人员不习惯编写跨平台软件的话。然而，项目确实有超出其初始范围的习惯，并且需要支持其他平台和生成器类型是相对常见的。定期使用与开发人员通常使用的项目生成器不同的项目生成器检查构建，可以通过阻止不需要的特定于生成器的代码来减少未来的痛苦。这还有一个好处是使该项目能够很好地利用未来任何新的发电机类型。一个好的策略是确保项目在每个感兴趣的平台上使用默认生成器类型以及其他类型进行构建。Ninja 生成器是后者的绝佳选择，因为它拥有所有生成器中最广泛的平台支持，并且还可以创建非常高效的构建。如果项目正在编写脚本，请通过调用构建工具， cmake --build而不是直接调用构建工具。这使得脚本可以轻松地在生成器类型之间切换，而无需进行修改。

It can be tempting to focus on using one particular type of project generator in the early stages of a project, especially if the developer is not accustomed to writing cross-platform software. Projects do, however, have a habit of growing beyond their initial scope and it is relatively common to need to support additional platforms and generator types. Periodically checking the build with a different project generator than the one a developer usually uses can save considerable future pain by discouraging generator-specific code where it isn’t required. This also has the benefit of making the project well placed to take advantage of any new generator type in the future. A good strategy is to ensure the project builds with the default generator type on each platform of interest, plus one other type. The Ninja generator is an excellent choice for the latter, since it has the broadest platform support of all the generators and it also creates very efficient builds. If the project is being scripted, invoke the build tool via cmake --build instead of invoking the build tool directly. This allows the script to easily switch between generator types without having to be modified.

3.1. 管理 CMake 版本

3.1. Managing CMake Versions

CMake 不断更新和扩展，以添加对新工具、平台和功能的支持。CMake 背后的开发人员非常小心地维护与每个新版本的向后兼容性，因此当用户更新到较新版本的 CMake 时，项目应该像以前一样继续构建。有时，特定的 CMake 行为需要更改，或者在新版本中可能会引入更严格的检查和警告。CMake 并没有要求所有项目立即处理此问题，而是提供了允许项目“表现得像 CMake 版本 XYZ”的策略机制。这允许 CMake 在内部修复错误并引入新功能，但仍保持任何特定过去版本的预期行为。

CMake is continually updated and extended to add support for new tools, platforms and features. The developers behind CMake are very careful to maintain backwards compatibility with each new release, so when users update to a newer version of CMake, projects should continue to build as they did before. Sometimes, a particular CMake behavior needs to change or more stringent checks and warnings may be introduced in newer versions. Rather than requiring all projects to immediately deal with this, CMake provides policy mechanisms which allow the project to say “Behave like CMake version X.Y.Z”. This allows CMake to fix bugs internally and introduce new features, but still maintain the expected behavior of any particular past release.

项目指定有关其预期 CMake 版本行为的详细信息的主要方式是使用命令cmake_minimum_required()。这应该是文件的第一行，CMakeLists.txt以便在其他任何事情之前检查和确定项目的需求。该命令做了两件事：

The primary way a project specifies details about its expected CMake version behavior is with the cmake_minimum_required() command. This should be the first line of the CMakeLists.txt file so that the project’s requirements are checked and established before anything else. This command does two things:

CMakeLists.txt使用此命令非常重要，如果该文件未在任何其他命令之前调用，CMake 将发出警告 cmake_minimum_required()。它需要知道如何为所有后续处理设置策略行为。cmake_minimum_required() 对于大多数项目，顾名思义，只需指定所需的最低 CMake 版本就足够了。事实上，它还意味着 CMake 的行为应该与特定版本相同，这可以被认为是一个有用的附带好处。第 12 章“策略”更详细地讨论了策略设置，并解释了如何根据需要调整此行为。

Using this command is so important that CMake will issue a warning if the CMakeLists.txt file does not call cmake_minimum_required() before any other command. It needs to know how to set up the policy behavior for all subsequent processing. For most projects, it is enough to treat cmake_minimum_required() as simply specifying the minimum required CMake version, as its name suggests. The fact that it also implies CMake should behave the same as that particular version can be considered a useful side benefit. Chapter 12, Policies discusses policy settings in more detail and explains how to tailor this behavior as needed.

该cmake_minimum_required()命令的典型形式很简单：

The typical form of the cmake_minimum_required() command is straightforward:

cmake_minimum_required(VERSION major.minor[.patch[.tweak]])

cmake_minimum_required(VERSION major.minor[.patch[.tweak]])

关键字VERSION必须始终存在，并且提供的版本详细信息必须至少包含该major.minor部分。在大多数项目中，指定 patch和tweak部分是不必要的，因为新功能通常只出现在次要版本更新中（这是从 3.0 版本开始的官方 CMake 行为）。仅当需要修复特定错误时，项目才应指定一个patch部分。此外，由于 3.x 系列中没有 CMake 版本使用过tweak数字，因此项目也不需要指定一个数字。

The VERSION keyword must always be present and the version details provided must have at least the major.minor part. In most projects, specifying the patch and tweak parts is not necessary, since new features typically only appear in minor version updates (this is the official CMake behavior from version 3.0 onward). Only if a specific bug fix is needed should a project specify a patch part. Furthermore, since no CMake release in the 3.x series has used a tweak number, projects should not need to specify one either.

开发人员应该仔细考虑他们的项目应该需要什么最低 CMake 版本。3.2 版本可能是任何新项目应该考虑的最旧的版本，因为它为现代 CMake 技术提供了相当完整的功能集。版本 2.8.12 的功能覆盖范围有所减少，缺乏许多有用的功能，但它可能适用于较旧的项目。之前的版本缺乏实质性功能，这使得许多现代 CMake 技术无法使用。如果使用快速移动的平台（例如 iOS），可能需要最新版本的 CMake 以支持最新的操作系统版本等。

Developers should think carefully about what minimum CMake version their project should require. Version 3.2 is perhaps the oldest any new project should consider, since it provides a reasonably complete feature set for modern CMake techniques. Version 2.8.12 has a reduced feature coverage, lacking a number of useful features but it may be workable for older projects. Versions before that lack substantial features that would make using many modern CMake techniques impossible. If working with fast-moving platforms such as iOS, quite recent versions of CMake may be needed in order to support the latest OS releases, etc.

作为一般经验法则，选择不会给项目构建人员带来重大问题的最新 CMake 版本。最大的困难通常是需要支持旧平台的项目，其中系统提供的 CMake 版本可能相当旧。对于这种情况，如果可能的话，开发人员应该考虑安装更新的版本，而不是限制自己使用非常旧的 CMake 版本。另一方面，如果该项目本身是其他项目的依赖项，那么选择更新的 CMake 版本可能会给采用带来障碍。在这种情况下，最好还是需要最旧的 CMake 版本，该版本仍提供所需的最低 CMake 功能，但如果可用，请使用较新 CMake 版本中的功能（第12 章，策略介绍了实现此目的的技术）。这将防止其他项目被迫需要比其目标环境通常允许或提供的更新的版本。如果依赖项目愿意，它们总是可以需要更新的版本，但不能需要较旧的版本。使用最旧的可用版本的主要缺点是，它可能会导致更多弃用警告，因为较新的 CMake 版本会警告较旧的行为，以鼓励项目自行更新。

As a general rule of thumb, choose the most recent CMake version that won’t present significant problems for those building the project. The greatest difficulty is typically experienced by projects that need to support older platforms where the system-provided version of CMake may be quite old. For such cases, if at all possible, developers should consider installing a more recent release rather than restricting themselves to very old CMake versions. On the other hand, if the project will itself be a dependency for other projects, then choosing a more recent CMake version may present a hurdle for adoption. In such cases, it may be beneficial to instead require the oldest CMake version that still provides the minimum CMake features needed, but make use of features from later CMake versions if available (Chapter 12, Policies presents techniques for achieving this). This will prevent other projects from being forced to require a more recent version than their target environment typically allows or provides. Dependent projects can always require a more recent version if they so wish, but they cannot require an older one. The main disadvantage of using the oldest workable version is that it may result in more deprecation warnings, since newer CMake versions will warn about older behaviors to encourage projects to update themselves.

3.2. 项目（）命令

3.2. The project() Command

每个 CMake 项目都应该包含一个命令，并且它应该在调用project()后出现。cmake_minimum_required()该命令及其最常见的选项具有以下形式：

Every CMake project should contain a project() command and it should appear after cmake_minimum_required() has been called. The command with its most common options has the following form:

project(projectName
        [VERSION major[.minor[.patch[.tweak]]]]
        [LANGUAGES languageName ...]
)

project(projectName
        [VERSION major[.minor[.patch[.tweak]]]]
        [LANGUAGES languageName ...]
)

是projectName必需的，并且只能包含字母、数字、下划线 (_) 和连字符 (-)，尽管在实践中通常只使用字母和下划线。由于不允许使用空格，因此项目名称不必用引号引起来。此名称用于带有某些项目生成器（例如 Xcode 和 Visual Studio）的项目的顶层，并且还用于项目的各个其他部分，例如充当打包和文档元数据的默认值、提供项目-特定变量等等。该名称是该命令的唯一强制参数 project()。

The projectName is required and may only contain letters, numbers, underscores (_) and hyphens (-), although typically only letters and perhaps underscores are used in practice. Since spaces are not permitted, the project name does not have to be surrounded by quotes. This name is used for the top level of a project with some project generators (eg Xcode and Visual Studio) and it is also used in various other parts of the project, such as to act as defaults for packaging and documentation metadata, to provide project-specific variables and so on. The name is the only mandatory argument for the project() command.

VERSION仅 CMake 3.0 及更高版本支持 可选详细信息。与 一样projectName，CMake 使用版本详细信息来填充一些变量并作为默认包元数据，但除此之外，版本详细信息没有任何其他意义。尽管如此，要养成的一个好习惯是在这里定义项目的版本，以便项目的其他部分可以引用它。第 20 章“指定版本详细信息”对此进行了深入介绍，并解释了如何在 CMakeLists.txt文件后面引用此版本信息。

The optional VERSION details are only supported in CMake 3.0 and later. Like the projectName, the version details are used by CMake to populate some variables and as default package metadata, but other than that, the version details don’t have any other significance. Nonetheless, a good habit to establish is to define the project’s version here so that other parts of the project can refer to it. Chapter 20, Specifying Version Details covers this in depth and explains how to refer to this version information later in the CMakeLists.txt file.

可选LANGUAGES参数定义应为项目启用的编程语言。支持的值包括C、CXX、Fortran、 ASM、CUDA等。如果指定多种语言，请用空格分隔每种语言。在某些特殊情况下，项目可能希望表明不使用任何语言，这可以使用LANGUAGES NONE. 后面章节中介绍的技术利用了这种特殊的形式。如果未 LANGUAGES提供选项，CMake 将默认为C和CXX。3.0 之前的 CMake 版本不支持该LANGUAGES关键字，但仍然可以使用旧形式的命令在项目名称后指定语言，如下所示：

The optional LANGUAGES argument defines the programming languages that should be enabled for the project. Supported values include C, CXX, Fortran, ASM, CUDA and others. If specifying multiple languages, separate each with a space. In some special situations, projects may want to indicate that no languages are used, which can be done using LANGUAGES NONE. Techniques introduced in later chapters take advantage of this particular form. If no LANGUAGES option is provided, CMake will default to C and CXX. CMake versions prior to 3.0 do not support the LANGUAGES keyword, but languages can still be specified after the project name using the older form of the command like so:

project(MyProj C CXX)

project(MyProj C CXX)

鼓励新项目指定至少 3.0 的最低 CMake 版本，并使用带有LANGUAGES关键字的新形式。

New projects are encouraged to specify a minimum CMake version of at least 3.0 and use the new form with the LANGUAGES keyword instead.

该project()命令的作用不仅仅是填充几个变量。它的重要职责之一是检查每种启用语言的编译器，并确保它们能够成功编译和链接。编译器和链接器设置的问题很快就会被发现。一旦这些检查通过，CMake 就会设置许多变量和属性来控制启用语言的构建。 第 22 章“工具链和交叉编译”更详细地讨论了这一领域，包括影响工具链选择和配置的各种方法。 第 7 章“使用子目录”还讨论了影响命令使用的其他注意事项和要求project()。

The project() command does much more than just populate a few variables. One of its important responsibilities is to check the compilers for each enabled language and ensure they are able to compile and link successfully. Problems with the compiler and linker setup are then caught very early. Once these checks have passed, CMake sets up a number of variables and properties which control the build for the enabled languages. Chapter 22, Toolchains And Cross Compiling discusses this area in much greater detail, including the various ways to influence toolchain selection and configuration. Chapter 7, Using Subdirectories also discusses additional considerations and requirements that affect the use of the project() command.

当 CMake 执行的编译器和链接器检查成功时，它们的结果将被缓存，以便在后续 CMake 运行中不必重复它们。这些缓存的详细信息存储在构建目录中的文件中 CMakeCache.txt。有关检查的其他详细信息可以在构建区域内的子目录中找到，但开发人员通常只需要在使用新的或不寻常的编译器或设置用于交叉编译的工具链文件时才需要查看那里。

When the compiler and linker checks performed by CMake are successful, their results are cached so that they do not have to be repeated in subsequent CMake runs. These cached details are stored in the build directory in the CMakeCache.txt file. Additional details about the checks can be found in subdirectories within the build area, but developers would typically only need to look there if working with a new or unusual compiler or when setting up toolchain files for cross-compiling.

3.3. 构建基本的可执行文件

3.3. Building A Basic Executable

为了完成我们的最小示例，该add_executable()命令告诉 CMake 从一组源文件创建一个可执行文件。该命令的基本形式是：

To complete our minimal example, the add_executable() command tells CMake to create an executable from a set of source files. The basic form of this command is:

add_executable(targetName source1 [source2 ...])

add_executable(targetName source1 [source2 ...])

这将创建一个可执行文件，可以在 CMake 项目中将其称为 targetName. 该名称可能包含字母、数字、下划线和连字符。构建项目时，将在构建目录中创建一个可执行文件，其名称与平台相关，默认名称基于目标名称。考虑以下简单的示例命令：

This creates an executable which can be referred to within the CMake project as targetName. This name may contain letters, numbers, underscores and hyphens. When the project is built, an executable will be created in the build directory with a platform-dependent name, the default name being based on the target name. Consider the following simple example command:

add_executable(MyApp main.cpp)

add_executable(MyApp main.cpp)

默认情况下，可执行文件的名称将MyApp.exe在 Windows 和 MyApp基于 Unix 的平台（如 macOS、Linux 等）上使用。可执行文件名称可以使用目标属性进行自定义，目标属性是第 9 章“属性”中介绍的 CMake 功能。CMakeLists.txt通过使用不同的目标名称多次调用，还可以在一个文件中定义多个可执行文件 add_executable()。如果在多个 add_executable()命令中使用相同的目标名称，CMake 将失败并突出显示错误。

By default, the name of the executable would be MyApp.exe on Windows and MyApp on Unix-based platforms like macOS, Linux, etc. The executable name can be customized with target properties, a CMake feature introduced in Chapter 9, Properties. Multiple executables can also be defined within the one CMakeLists.txt file by calling add_executable() multiple times with different target names. If the same target name is used in more than one add_executable() command, CMake will fail and highlight the error.

3.4. 评论

3.4. Commenting

在离开本章之前，演示如何向CMakeLists.txt文件添加注释将很有用。本书中广泛使用了注释，并鼓励开发人员养成对项目进行注释的习惯，就像对普通源代码进行注释一样。CMake 遵循与 Unix shell 脚本类似的注释约定。任何以 # 字符开头的行都被视为注释。除了在带引号的字符串中之外，文件中行中 # 后面的任何内容CMakeLists.txt也被视为注释。下面显示了一些注释示例，并汇集了本章介绍的概念：

Before leaving this chapter, it will be useful to demonstrate how to add comments to a CMakeLists.txt file. Comments are used extensively throughout this book and developers are encouraged to also get into the habit of commenting their projects just as they would for ordinary source code. CMake follows similar commenting conventions as Unix shell scripts. Any line beginning with a # character is treated as a comment. Except within a quoted string, anything after a # on a line within a CMakeLists.txt file is also treated as a comment. The following shows a few comment examples and brings together the concepts introduced in this chapter:

cmake_minimum_required(VERSION 3.2)

# We don't use the C++ compiler, so don't let project()
# test for it in case the platform doesn't have one
project(MyApp VERSION 4.7.2 LANGUAGES C)

# Primary tool for this project
add_executable(MainTool
    main.c
    debug.c   # Optimized away for release builds
)

# Helpful diagnostic tool for development and testing
add_executable(TestTool testTool.c)

cmake_minimum_required(VERSION 3.2)

# We don't use the C++ compiler, so don't let project()
# test for it in case the platform doesn't have one
project(MyApp VERSION 4.7.2 LANGUAGES C)

# Primary tool for this project
add_executable(MainTool
    main.c
    debug.c   # Optimized away for release builds
)

# Helpful diagnostic tool for development and testing
add_executable(TestTool testTool.c)

3.5. 推荐做法

3.5. Recommended Practices

确保每个 CMake 项目都有一个cmake_minimum_required()命令作为其顶级CMakeLists.txt文件的第一行。在决定指定的最低所需版本号时，请记住版本越晚，项目能够使用的 CMake 功能就越多。这也意味着该项目可能会更好地适应新的平台或操作系统版本，这不可避免地会引入构建系统需要处理的新事物。相反，如果创建一个旨在作为操作系统本身的一部分进行构建和分发的项目（对于 Linux 来说很常见），则最低 CMake 版本可能由同一发行版提供的 CMake 版本决定。

Ensure every CMake project has a cmake_minimum_required() command as the first line of its top level CMakeLists.txt file. When deciding the minimum required version number to specify, keep in mind that the later the version, the more CMake features the project will be able to use. It will also mean the project is likely to be better placed to adapt to new platform or operating system releases, which inevitably introduce new things for build systems to deal with. Conversely, if creating a project intended to be built and distributed as part of the operating system itself (common for Linux), the minimum CMake version is likely to be dictated by the version of CMake provided by that same distribution.

如果项目需要 CMake 3.0 或更高版本，那么尽早强制考虑项目版本号并project()尽快开始将版本号合并到命令中也是不错的选择。克服现有流程的惯性并改变项目后期处理版本号的方式可能非常困难。在决定版本控制策略时，请考虑流行的做法，例如 语义版本控制。

If the project can require CMake 3.0 or later, it is also good to force thinking about project version numbers early and start incorporating version numbering into the project() command as soon as possible. It can be very hard to overcome the inertia of existing processes and change how version numbers are handled later in the life of a project. Consider popular practices such as Semantic Versioning when deciding on a versioning strategy.

4.1. 可执行文件

4.1. Executables

基本命令的更完整形式add_executable()如下：

The more complete form of the basic add_executable() command is as follows:

add_executable(targetName [WIN32] [MACOSX_BUNDLE]
               [EXCLUDE_FROM_ALL]
               source1 [source2 ...]
)

add_executable(targetName [WIN32] [MACOSX_BUNDLE]
               [EXCLUDE_FROM_ALL]
               source1 [source2 ...]
)

与之前显示的表单的唯一区别是新的可选关键字。

The only differences to the form shown previously are the new optional keywords.

除了上述内容之外，还有其他形式的命令add_executable() ，它们生成对现有可执行文件或目标的一种引用，而不是定义要构建的新可执行文件或目标。这些别名可执行文件在第 17 章目标类型中有详细介绍。

In addition to the above, there are other forms of the add_executable() command which produce a kind of reference to an existing executable or target rather than defining a new one to be built. These alias executables are covered in detail in Chapter 17, Target Types.

4.2. 定义库

4.2. Defining Libraries

创建简单的可执行文件是任何构建系统的基本需求。对于许多大型项目来说，创建和使用库的能力对于保持项目的可管理性也至关重要。CMake 支持构建各种不同类型的库，考虑到许多平台差异，但仍然支持每个库的本机特性。库目标是使用add_library()命令定义的，该命令有多种形式。其中最基本的如下：

Creating simple executables is a fundamental need of any build system. For many larger projects, the ability to create and work with libraries is also essential to keep the project manageable. CMake supports building a variety of different kinds of libraries, taking care of many of the platform differences, but still supporting the native idiosyncrasies of each. Library targets are defined using the add_library() command, of which there are a number of forms. The most basic of these is the following:

add_library(targetName [STATIC | SHARED | MODULE]
            [EXCLUDE_FROM_ALL]
            source1 [source2 ...]
)

add_library(targetName [STATIC | SHARED | MODULE]
            [EXCLUDE_FROM_ALL]
            source1 [source2 ...]
)

这种形式类似于如何add_executable()定义简单的可执行文件。targetName在文件中使用来CMakeLists.txt引用库，文件系统上构建的库的名称默认源自该名称。该EXCLUDE_FROM_ALL关键字与 的效果完全相同add_executable()，即防止库包含在默认ALL目标中。要构建的库的类型由其余三个关键字之一指定STATIC，SHARED 或MODULE。

This form is analogous to how add_executable() is used to define a simple executable. The targetName is used within the CMakeLists.txt file to refer to the library, with the name of the built library on the file system being derived from this name by default. The EXCLUDE_FROM_ALL keyword has exactly the same effect as it does for add_executable(), namely to prevent the library from being included in the default ALL target. The type of library to be built is specified by one of the remaining three keywords STATIC, SHARED or MODULE.

可以省略定义要构建的库类型的关键字。除非项目特别需要特定类型的库，否则首选做法是不指定它，并将选择权留给开发人员在构建项目时。在这种情况下，库将是 STATIC或SHARED，选择由名为 的 CMake 变量的值决定BUILD_SHARED_LIBS。如果BUILD_SHARED_LIBS已设置为 true，则库目标将是共享库，否则它将是静态的。第 5 章变量中详细介绍了如何使用变量，但目前，设置此变量的一种方法是-D在命令行中包含一个选项，cmake 如下所示：

It is possible to omit the keyword defining what type of library to build. Unless the project specifically requires a particular type of library, the preferred practice is to not specify it and leave the choice up to the developer when building the project. In such cases, the library will be either STATIC or SHARED, with the choice determined by the value of a CMake variable called BUILD_SHARED_LIBS. If BUILD_SHARED_LIBS has been set to true, the library target will be a shared library, otherwise it will be static. Working with variables is covered in detail in Chapter 5, Variables, but for now, one way to set this variable is by including a -D option on the cmake command line like so:

cmake -DBUILD_SHARED_LIBS=YES /路径/到/源

cmake -DBUILD_SHARED_LIBS=YES /path/to/source

它可以在CMakeLists.txt文件中设置，而不是在任何命令之前放置以下内容add_library()，但这将需要开发人员在想要更改它时对其进行修改（即，它会不太灵活）：

It could be set in the CMakeLists.txt file instead with the following placed before any add_library() commands, but that would then require developers to modify it if they wanted to change it (i.e. it would be less flexible):

set(BUILD_SHARED_LIBS YES)

set(BUILD_SHARED_LIBS YES)

就像可执行文件一样，库目标也可以定义为引用某些现有的二进制文件或目标，而不是由项目构建。还支持另一种类型的伪库，用于将目标文件收集在一起，而无需创建静态库。这些都在第 17 章目标类型中详细讨论。

Just as for executables, library targets can also be defined to refer to some existing binary or target rather than being built by the project. Another type of pseudo-library is also supported for collecting together object files without going as far as creating a static library. These are all discussed in detail in Chapter 17, Target Types.

4.3. 链接目标

4.3. Linking Targets

在考虑构成项目的目标时，开发人员通常习惯于考虑库 A 需要库 B，因此 A 链接到 B。这是查看库处理的传统方式，其中一个库需要一个库的想法另一个则非常简单。然而，实际上，库之间可能存在几种不同类型的依赖关系：

When considering the targets that make up a project, developers are typically used to thinking in terms of library A needing library B, so A is linked to B. This is the traditional way of looking at library handling, where the idea of one library needing another is very simplistic. In reality, however, there are a few different types of dependency relationships that can exist between libraries:

CMake 通过其命令捕获了更丰富的依赖关系集 target_link_libraries()，而不仅仅是需要链接的简单想法。命令的一般形式为：

CMake captures this richer set of dependency relationships with its target_link_libraries() command, not just the simplistic idea of needing to link. The general form of the command is:

target_link_libraries(targetName
     <PRIVATE|PUBLIC|INTERFACE> item1 [item2 ...]
    [<PRIVATE|PUBLIC|INTERFACE> item3 [item4 ...]]
    ...
)

target_link_libraries(targetName
     <PRIVATE|PUBLIC|INTERFACE> item1 [item2 ...]
    [<PRIVATE|PUBLIC|INTERFACE> item3 [item4 ...]]
    ...
)

这使得项目能够精确定义一个库如何依赖其他库。然后，CMake 负责管理以这种方式链接的整个库链中的依赖关系。例如，请考虑以下情况：

This allows projects to precisely define how one library depends on others. CMake then takes care of managing the dependencies throughout the chain of libraries linked in this fashion. For example, consider the following:

add_library(Collector src1.cpp)
add_library(Algo src2.cpp)
add_library(Engine src3.cpp)
add_library(Ui src4.cpp)
add_executable(MyApp main.cpp)

target_link_libraries(Collector
    PUBLIC  Ui
    PRIVATE Algo Engine
)
target_link_libraries(MyApp PRIVATE Collector)

add_library(Collector src1.cpp)
add_library(Algo src2.cpp)
add_library(Engine src3.cpp)
add_library(Ui src4.cpp)
add_executable(MyApp main.cpp)

target_link_libraries(Collector
    PUBLIC  Ui
    PRIVATE Algo Engine
)
target_link_libraries(MyApp PRIVATE Collector)

在此示例中，Ui库作为 链接到Collector库 PUBLIC，因此即使仅MyApp直接链接到Collector，MyApp 也会Ui由于这种PUBLIC关系而链接到。另一方面， 和 库链接到as ， 因此不会直接链接到它们 Algo 。第 17.2 节“库”讨论了静态库的其他行为，这些行为可能导致进一步链接以满足依赖关系，包括循环依赖关系。EngineCollectorPRIVATEMyApp

In this example, the Ui library is linked to the Collector library as PUBLIC, so even though MyApp only directly links to Collector, MyApp will also be linked to Ui because of that PUBLIC relationship. The Algo and Engine libraries, on the other hand, are linked to Collector as PRIVATE, so MyApp will not be directly linked to them. Section 17.2, “Libraries” discusses additional behaviors for static libraries which may result in further linking to satisfy dependency relationships, including cyclic dependencies.

后面的章节介绍了一些其他target_…​()命令，这些命令进一步增强了目标之间携带的依赖性信息。这些允许编译器/链接器标志和标头搜索路径在通过 . 连接时也从一个目标传递到另一个目标target_link_libraries()。这些功能从 CMake 2.8.11 到 3.2 逐步添加，并导致CMakeLists.txt文件变得更加简单和强大。

Later chapters present a few other target_…​() commands which further enhance the dependency information carried between targets. These allow compiler/linker flags and header search paths to also carry through from one target to another when they are connected by target_link_libraries(). These features were added progressively from CMake 2.8.11 through to 3.2 and lead to considerably simpler and more robust CMakeLists.txt files.

后面的章节还讨论了更复杂的源目录层次结构的使用。在这种情况下，如果使用 CMake 3.12 或更早版本，则targetName 使用的 with必须由调用的同一目录中的 or命令target_link_libraries()定义 （此限制在 CMake 3.13 中已删除）。add_executable()add_library()target_link_libraries()

Later chapters also discuss the use of more complex source directory hierarchies. In such cases, if using CMake 3.12 or earlier, the targetName used with target_link_libraries() must have been defined by an add_executable() or add_library() command in the same directory from which target_link_libraries() is being called (this restriction was removed in CMake 3.13).

4.4. 链接非目标

4.4. Linking Non-targets

在上一节中，链接到的所有项目都是现有的 CMake 目标，但该target_link_libraries()命令比这更灵活。除了 CMake 目标之外，还可以将以下内容指定为target_link_libraries()命令中的项目：

In the preceding section, all the items being linked to were existing CMake targets, but the target_link_libraries() command is more flexible than that. In addition to CMake targets, the following things can also be specified as items in a target_link_libraries() command:

除上述内容外，由于历史原因，任何项目前面都可能带有关键字debug、optimized或 之一general。这些关键字的作用是根据构建是否配置为调试构建来进一步细化何时应包含其后面的项目（请参阅第 14 章，构建类型）。如果某个项目前面有debug关键字，则仅当构建是调试构建时才会添加它。如果某个项目前面有 optimized关键字，则仅当构建不是调试构建时才会添加该项目。关键字general指定应为所有构建配置添加该项目，如果不使用关键字，这无论如何都是默认行为。debug新项目应避免使用,optimized和关键字general，因为有更清晰、更灵活和更强大的方法可以使用当今的 CMake 功能实现相同的目标。

In addition to the above, for historical reasons, any item may be preceded by one of the keywords debug, optimized or general. The effect of these keywords is to further refine when the item following it should be included based on whether or not the build is configured as a debug build (see Chapter 14, Build Type). If an item is preceded by the debug keyword, then it will only be added if the build is a debug build. If an item is preceded by the optimized keyword, it will only be added if the build is not a debug build. The general keyword specifies that the item should be added for all build configurations, which is the default behavior anyway if no keyword is used. The debug, optimized and general keywords should be avoided for new projects as there are clearer, more flexible and more robust ways to achieve the same thing with today’s CMake features.

4.5. 旧式 CMake

4.5. Old-style CMake

该target_link_libraries()命令还有一些其他形式，其中一些形式早在 2.8.11 版本之前就已成为 CMake 的一部分。此处讨论这些形式是为了帮助理解旧的 CMake 项目，但通常不鼓励在新项目中使用它们。前面显示的完整形式PRIVATE，PUBLIC以及 和INTERFACE部分应该是首选，因为它更准确地表达了依赖关系的本质。

The target_link_libraries() command also has a few other forms, some of which have been part of CMake from well before version 2.8.11. These forms are discussed here for the benefit of understanding older CMake projects, but their use is generally discouraged for new projects. The full form shown previously with PRIVATE, PUBLIC and INTERFACE sections should be preferred, as it expresses the nature of dependencies with more accuracy.

target_link_libraries(targetName item [item...])

target_link_libraries(targetName item [item...])

上述形式通常等同于被定义为 的项目PUBLIC，但在某些情况下，它们可以被视为PRIVATE。特别是，如果项目定义了一个混合了新旧形式命令的库依赖项链，则旧式形式通常会被视为PRIVATE.

The above form is generally equivalent to the items being defined as PUBLIC, but in certain situations, they may instead be treated as PRIVATE. In particular, if a project defines a chain of library dependencies with a mix of both old and new forms of the command, the old-style form will generally be treated as PRIVATE.

另一种受支持但已弃用的形式如下：

Another supported but deprecated form is the following:

target_link_libraries(targetName
    LINK_INTERFACE_LIBRARIES item [item...]
)

target_link_libraries(targetName
    LINK_INTERFACE_LIBRARIES item [item...]
)

这是INTERFACE上面介绍的较新形式的关键字的前体，但 CMake 文档不鼓励使用它。其行为可以影响不同的目标属性，并由策略设置控制该行为。这对开发人员来说是一个潜在的混乱来源，可以通过使用更新的INTERFACE形式来避免。

This is a pre-cursor to the INTERFACE keyword of the newer form covered above, but its use is discouraged by the CMake documentation. Its behavior can affect different target properties, with the policy settings controlling that behavior. This is a potential source of confusion for developers which can be avoided by using the newer INTERFACE form instead.

target_link_libraries(targetName
    <LINK_PRIVATE|LINK_PUBLIC> lib [lib...]
   [<LINK_PRIVATE|LINK_PUBLIC> lib [lib...]]
)

target_link_libraries(targetName
    <LINK_PRIVATE|LINK_PUBLIC> lib [lib...]
   [<LINK_PRIVATE|LINK_PUBLIC> lib [lib...]]
)

与之前的旧式表单类似，此表单是 新表单的PRIVATE和关键字版本的前身。PUBLIC同样，旧式形式对于它影响哪些目标属性也存在同样的混乱，并且 PRIVATE/PUBLIC关键字形式应该是新项目的首选。

Similar to the previous old-style form, this one is a pre-cursor to the PRIVATE and PUBLIC keyword versions of the newer form. Again, the old-style form has the same confusion over which target properties it affects and the PRIVATE/PUBLIC keyword form should be preferred for new projects.

4.6. 推荐做法

4.6. Recommended Practices

目标名称不需要与项目名称相关。教程和示例使用变量作为项目名称并重用该变量作为可执行目标的名称是很常见的，如下所示：

Target names need not be related to the project name. It is common to see tutorials and examples use a variable for the project name and reuse that variable for the name of an executable target like so:

# Poor practice, but very common
set(projectName MyExample)
project(${projectName})
add_executable(${projectName} ...)

# Poor practice, but very common
set(projectName MyExample)
project(${projectName})
add_executable(${projectName} ...)

这仅适用于最基本的项目，并会助长许多坏习惯。将项目名称和可执行文件名称视为独立的，即使它们最初是相同的。直接设置项目名称而不是通过变量，根据目标的用途而不是其所属的项目选择目标名称，并假设项目最终需要定义多个目标。这可以强化更好的习惯，这在处理更复杂的多目标项目时非常重要。

This only works for the most basic of projects and encourages a number of bad habits. Consider the project name and executable name as being separate, even if initially they start out the same. Set the project name directly rather than via a variable, choose a target name according to what the target does rather than the project it is part of and assume the project will eventually need to define more than one target. This reinforces better habits which will be important when working on more complex multi-target projects.

为库的目标命名时，请抵制以 . 开头或结尾的诱惑lib。在许多平台上（即除了 Windows 之外的几乎所有平台），lib在构建实际的库名称时将自动添加前导前缀，以使其符合平台的通常约定。如果目标名称已经以 开头lib，则生成的库文件名将以 的形式结尾liblibsomething…​.，人们通常认为这是一个错误。

When naming targets for libraries, resist the temptation to start or end the name with lib. On many platforms (i.e. just about all except Windows), a leading lib will be prefixed automatically when constructing the actual library name to make it conform to the platform’s usual convention. If the target name already begins with lib, the resultant library file names end up with the form liblibsomething…​., which people often assume to be a mistake.

除非有充分的理由这样做，否则请尽量避免为库指定STATIC orSHARED关键字，直到知道需要它为止。这使得在静态或动态库之间进行选择作为整个项目范围的策略具有更大的灵活性。该BUILD_SHARED_LIBS变量可用于在一个位置更改默认值，而不必修改每次调用 add_library().

Unless there are strong reasons to do so, try to avoid specifying the STATIC or SHARED keyword for a library until it is known to be needed. This allows greater flexibility in choosing between static or dynamic libraries as an overall project-wide strategy. The BUILD_SHARED_LIBS variable can be used to change the default in one place instead of having to modify every call to add_library().

目标是在调用命令时始终指定PRIVATE,PUBLIC和/或INTERFACE关键字，target_link_libraries()而不是遵循旧式 CMake 语法（假设所有内容都是PUBLIC. 随着项目复杂性的增加，这三个关键字对如何处理目标间依赖关系产生更大的影响。从项目一开始就使用它们还迫使开发人员考虑目标之间的依赖关系，这有助于更早地突出项目中的结构问题。

Aim to always specify PRIVATE, PUBLIC and/or INTERFACE keywords when calling the target_link_libraries() command rather than following the old-style CMake syntax which assumed everything was PUBLIC. As a project grows in complexity, these three keywords have a stronger impact on how inter-target dependencies are handled. Using them from the beginning of a project also forces developers to think about the dependencies between targets, which can help to highlight structural problems within the project much earlier.

5.1. 变量基础知识

5.1. Variable Basics

与任何计算语言一样，变量是 CMake 中完成任务的基石。定义变量的最基本方法是使用命令set()。普通变量可以在文件中定义CMakeLists.txt如下：

Like any computing language, variables are a cornerstone of getting things done in CMake. The most basic way of defining a variable is with the set() command. A normal variable can be defined in a CMakeLists.txt file as follows:

set(varName value... [PARENT_SCOPE])

set(varName value... [PARENT_SCOPE])

变量名称varName可以包含字母、数字和下划线，字母区分大小写。名称中也可能包含字符./-+，但在实践中很少见到。其他字符也可以通过间接方式实现，但同样，这些字符在正常使用中通常不会出现。

The name of the variable, varName, can contain letters, numbers and underscores, with letters being case-sensitive. The name may also contain the characters ./-+ but these are rarely seen in practice. Other characters are also possible via indirect means, but again, these are not typically seen in normal use.

在 CMake 中，变量具有特定的作用域，就像其他语言中的变量的作用域仅限于特定的函数、文件等一样。变量不能在其作用域之外读取或修改。与其他语言相比，CMake 中的变量作用域更加灵活，但目前，在本章的简单示例中，将变量的作用域视为全局变量。 第 7 章“使用子目录”和第 8 章“函数和宏”介绍了出现局部作用域的情况，并展示了如何PARENT_SCOPE使用关键字来提高变量在封闭作用域中的可见性。

In CMake, a variable has a particular scope, much like how variables in other languages have scope limited to a particular function, file, etc. A variable cannot be read or modified outside of its scope. Compared to other languages, variable scope is a little more flexible in CMake, but for now, in the simple examples in this chapter, consider the scope of a variable as being global. Chapter 7, Using Subdirectories and Chapter 8, Functions And Macros introduce the situations where local scopes arise and show how the PARENT_SCOPE keyword is used to promote the visibility of a variable into the enclosing scope.

CMake 将所有变量视为字符串。在各种上下文中，变量可能被解释为不同的类型，但最终它们只是字符串。设置变量的值时，CMake 不要求将这些值加引号，除非该值包含空格。如果给出多个值，这些值将连接在一起并用分号分隔每个值 - 生成的字符串是 CMake 表示列表的方式。以下内容应有助于演示该行为。

CMake treats all variables as strings. In various contexts, variables may be interpreted as a different type, but ultimately, they are just strings. When setting a variable’s value, CMake doesn’t require those values to be quoted unless the value contains spaces. If multiple values are given, the values will be joined together with a semicolon separating each value - the resultant string is how CMake represents lists. The following should help to demonstrate the behavior.

set(myVar a b c)    # myVar = "a;b;c"
set(myVar a;b;c)    # myVar = "a;b;c"
set(myVar "a b c")  # myVar = "a b c"
set(myVar a b;c)    # myVar = "a;b;c"
set(myVar a "b c")  # myVar = "a;b c"

set(myVar a b c)    # myVar = "a;b;c"
set(myVar a;b;c)    # myVar = "a;b;c"
set(myVar "a b c")  # myVar = "a b c"
set(myVar a b;c)    # myVar = "a;b;c"
set(myVar a "b c")  # myVar = "a;b c"

变量的值是通过 获得的${myVar}，它可以在任何需要字符串或变量的地方使用。CMake 特别灵活，因为还可以递归地使用此形式或指定要设置的另一个变量的名称。此外，CMake 不需要在使用变量之前定义它们。使用未定义的变量只会导致替换为空字符串，类似于 Unix shell 脚本的行为方式。默认情况下，使用未定义的变量不会发出警告，但 --warn-uninitialized可以向cmake命令提供该选项以启用此类警告。但请注意，这种使用很常见，并不一定是问题的症状，因此该选项的用途可能会受到限制。

The value of a variable is obtained with ${myVar}, which can be used anywhere a string or variable is expected. CMake is particularly flexible in that it is also possible to use this form recursively or to specify the name of another variable to set. In addition, CMake doesn’t require variables to be defined before using them. Use of an undefined variable simply results in an empty string being substituted, similar to the way Unix shell scripts behave. By default, no warning is issued for use of an undefined variable, but the --warn-uninitialized option can be given to the cmake command to enable such warnings. Be aware, however, that such use is very common and is not necessarily a symptom of a problem, so the option’s usefulness may be limited.

set(foo ab)               # foo   = "ab"
set(bar ${foo}cd)         # bar   = "abcd"
set(baz ${foo} cd)        # baz   = "ab;cd"
set(myVar ba)             # myVar = "ba"
set(big "${${myVar}r}ef") # big   = "${bar}ef" = "abcdef"
set(${foo} xyz)           # ab    = "xyz"
set(bar ${notSetVar})     # bar   = ""

set(foo ab)               # foo   = "ab"
set(bar ${foo}cd)         # bar   = "abcd"
set(baz ${foo} cd)        # baz   = "ab;cd"
set(myVar ba)             # myVar = "ba"
set(big "${${myVar}r}ef") # big   = "${bar}ef" = "abcdef"
set(${foo} xyz)           # ab    = "xyz"
set(bar ${notSetVar})     # bar   = ""

字符串不限于单行，它们可以包含嵌入的换行符。它们还可以包含引号，需要用反斜杠转义。

Strings are not restricted to being a single line, they can contain embedded newline characters. They can also contain quotes, which require escaping with backslashes.

set(myVar "goes here")
set(multiLine "First line ${myVar}
Second line with a \"quoted\" word")

set(myVar "goes here")
set(multiLine "First line ${myVar}
Second line with a \"quoted\" word")

如果使用 CMake 3.0 或更高版本，引号的替代方法是使用受 lua 启发的括号语法，其中内容的开头由 标记[=[ ，结尾由 标记]=]。方括号之间可以出现任意数量的=字符，包括根本不出现，但=开头和结尾必须使用相同数量的字符。如果左括号后紧跟一个换行符，则第一个换行符将被忽略，但后续的换行符不会被忽略。此外，不会对括号内的内容进行进一步的转换（即没有变量替换或转义）。

If using CMake 3.0 or later, an alternative to quotes is to use the lua-inspired bracket syntax where the start of the content is marked by [=[ and the end with ]=]. Any number of = characters can appear between the square brackets, including none at all, but the same number of = characters must be used at the start and the end. If the opening brackets are immediately followed by a newline character, that first newline is ignored, but subsequent newlines are not. Furthermore, no further transformation of the bracketed content is performed (i.e. no variable substitution or escaping).

# Simple multi-line content with bracket syntax,
# no = needed between the square bracket markers
set(multiLine [[
First line
Second line
]])

# Bracket syntax prevents unwanted substitution
set(shellScript [=[
#!/bin/bash

[[ -n "${USER}" ]] && echo "Have USER"
]=])

# Equivalent code without bracket syntax
set(shellScript
"#!/bin/bash

[[ -n \"\${USER}\" ]] && echo \"Have USER\"
")

# Simple multi-line content with bracket syntax,
# no = needed between the square bracket markers
set(multiLine [[
First line
Second line
]])

# Bracket syntax prevents unwanted substitution
set(shellScript [=[
#!/bin/bash

[[ -n "${USER}" ]] && echo "Have USER"
]=])

# Equivalent code without bracket syntax
set(shellScript
"#!/bin/bash

[[ -n \"\${USER}\" ]] && echo \"Have USER\"
")

如上面的示例所示，括号语法特别适合定义 Unix shell 脚本等内容。此类内容将${…​}语法用于其自身目的，并且经常包含引号，但使用括号语法意味着这些内容不必转义，这与定义 CMake 内容的传统引用样式不同。在和标记之间灵活使用任意数量的= 字符也意味着嵌入的方括号不会被误解为标记。第 19 章，使用文件包含更多示例，突出显示括号语法可以成为更好的替代方案的情况。[]

As the above example shows, bracket syntax is particularly well suited to defining content like Unix shell scripts. Such content uses the ${…​} syntax for its own purpose and frequently contains quotes, but using bracket syntax means these things do not have to be escaped, unlike the traditional quoting style of defining CMake content. The flexibility to use any number of = characters between the [ and ] markers also means embedded square brackets do not get misinterpreted as markers. Chapter 19, Working With Files includes further examples which highlight situations where bracket syntax can be a better alternative.

可以通过调用unset()或set() 不带指定变量值的调用来取消设置变量。以下内容是等效的，如果myVar尚不存在，则不会出现错误或警告：

A variable can be unset either by calling unset() or by calling set() with no value for the named variable. The following are equivalent, with no error or warning if myVar does not already exist:

set(myVar)
unset(myVar)

set(myVar)
unset(myVar)

除了项目定义供其自身使用的变量之外，许多 CMake 命令的行为还可能受到调用命令时特定变量的值的影响。这是 CMake 用于定制命令行为或修改默认值的常见模式，因此不必对每个命令、目标定义等重复它们。每个命令的 CMake 参考文档通常列出了可能影响该命令的任何变量。行为。本书的后续章节还重点介绍了许多有用的变量以及它们影响构建或提供有关构建的信息的方式。

In addition to variables defined by the project for its own use, the behavior of many of CMake’s commands can be influenced by the value of specific variables at the time the command is called. This is a common pattern used by CMake to tailor command behavior or to modify defaults so they don’t have to be repeated for every command, target definition, etc. The CMake reference documentation for each command typically lists any variables which can affect that command’s behavior. Later chapters of this book also highlight a number of useful variables and the way they affect or give information about the build.

5.2. 环境变量

5.2. Environment Variables

CMake 还允许使用 CMake 变量表示法的修改形式来检索和设置环境变量的值。环境变量的值是使用特殊形式获得的$ENV{varName}，并且可以在可以使用常规${varName}形式的任何地方使用。设置环境变量的方式与 CMake 变量类似，只不过使用而ENV{varName}不是仅varName作为要设置的变量。例如：

CMake also allows the value of environment variables to be retrieved and set using a modified form of the CMake variable notation. The value of an environment variable is obtained using the special form $ENV{varName} and this can be used anywhere a regular ${varName} form can be used. Setting an environment variable can be done in a similar way to a CMake variable, except with ENV{varName} instead of just varName as the variable to set. For example:

set(ENV{PATH} "$ENV{PATH}:/opt/myDir")

set(ENV{PATH} "$ENV{PATH}:/opt/myDir")

但请注意，设置这样的环境变量只会影响当前运行的 CMake 实例。CMake 运行完成后，对环境变量的更改就会丢失。特别是，对环境变量的更改在构建时将不可见。因此，CMakeLists.txt像这样在文件中设置环境变量很少有用。

Note, however, that setting an environment variable like this only affects the currently running CMake instance. As soon as the CMake run is finished, the change to the environment variable is lost. In particular, the change to the environment variable will not be visible at build time. Therefore, setting environment variables within the CMakeLists.txt file like this is rarely useful.

5.3. 缓存变量

5.3. Cache Variables

除了上面讨论的普通变量之外，CMake 还支持缓存 变量。与生命周期仅限于文件处理的普通变量不同CMakeLists.txt，缓存变量存储在CMakeCache.txt构建目录中调用的特殊文件中，并且它们在 CMake 运行之间持续存在。一旦设置，缓存变量将保持设置状态，直到某些内容明确地将它们从缓存中删除。缓存变量的值的检索方式与普通变量完全相同（即使用形式 ${myVar}），但set()用于设置缓存变量时的命令不同：

In addition to normal variables discussed above, CMake also supports cache variables. Unlike normal variables which have a lifetime limited to the processing of the CMakeLists.txt file, cache variables are stored in the special file called CMakeCache.txt in the build directory and they persist between CMake runs. Once set, cache variables remain set until something explicitly removes them from the cache. The value of a cache variable is retrieved in exactly the same way as a normal variable (i.e. with the ${myVar} form), but the set() command is different when used to set a cache variable:

set(varName value... CACHE type "docstring" [FORCE])

set(varName value... CACHE type "docstring" [FORCE])

当CACHE存在关键字时，该set()命令将应用于指定的缓存变量varName而不是普通变量。缓存变量比普通变量附加了更多信息，包括标称类型和文档字符串。设置缓存变量时必须提供两者，尽管docstring 可以为空。文档字符串不会影响 CMake 处理变量的方式，它仅由 GUI 工具使用来提供帮助详细信息、工具提示等内容。

When the CACHE keyword is present, the set() command will apply to a cache variable named varName instead of a normal variable. Cache variables have more information attached to them than a normal variable, including a nominal type and a documentation string. Both must be provided when setting a cache variable, although the docstring can be empty. The documentation string does not affect how CMake treats the variable, it is used only by GUI tools to provide things like help details, tooltips, etc.

CMake 在处理过程中始终将变量视为字符串。主要type用于改善 GUI 工具的用户体验，下一节将讨论一些值得注意的例外情况。必须type是以下之一：

CMake will always treat the variable as a string during processing. The type is used mostly to improve the user experience in GUI tools, with some notable exceptions discussed in the next section. The type must be one of the following:

GUI 工具通常使用docstring作为缓存变量的工具提示或在选择变量时作为简短的一行描述。应该docstring 很短并且由纯文本组成（即没有 HTML 标记等）。

GUI tools typically use the docstring as a tooltip for the cache variable or as a short one line description when the variable is selected. The docstring should be short and consist of plain text (i.e. no HTML markup, etc.).

设置布尔缓存变量是一种常见的需求，CMake 为其提供了一个单独的命令。set()开发人员可以使用以下命令， 而不是使用有点冗长的命令option()：

Setting a boolean cache variable is such a common need that CMake provides a separate command for it. Rather than the somewhat verbose set() command, developers can use option() instead:

option(optVar helpString [initialValue])

option(optVar helpString [initialValue])

如果initialValue省略，OFF将使用默认值。如果提供，则initialValue必须符合命令接受的布尔值之一set()。作为参考，上面的内容可以被认为或多或少等同于：

If initialValue is omitted, the default value OFF will be used. If provided, the initialValue must conform to one of the boolean values accepted by the set() command. For reference, the above can be thought of as more or less equivalent to:

set(optVar initialValue CACHE BOOL helpString)

set(optVar initialValue CACHE BOOL helpString)

与 相比set()，该option()命令更清楚地表达了布尔缓存变量的行为，因此它通常是首选使用的命令。但请注意，在某些情况下这两个命令的效果可能会有所不同（请参阅下一节）。

Compared to set(), the option() command more clearly expresses the behavior for boolean cache variables, so it would generally be the preferred command to use. Be aware, however, that the effect of the two commands can be different in certain situations (see the next section).

普通变量和缓存变量之间的一个重要区别是，如果存在关键字，该set() 命令只会覆盖缓存变量，这与普通变量不同，命令将始终覆盖预先存在的值。当用于定义缓存变量时，该命令的行为更像是 set-if-not-set，命令也是如此（它没有 功能）。主要原因是缓存变量主要用作开发人员的自定义点。可以使用缓存变量，而不是将文件中的值硬编码为普通变量，以便开发人员可以覆盖该值，而无需编辑文件 。该变量可以通过交互式 GUI 工具或脚本进行修改，而无需更改项目本身的任何内容。FORCEset()set()option()FORCECMakeLists.txtCMakeLists.txt

An important difference between normal and cache variables is that the set() command will only overwrite a cache variable if the FORCE keyword is present, unlike normal variables where the set() command will always overwrite a pre-existing value. The set() command acts more like set-if-not-set when used to define cache variables, as does the option() command (which has no FORCE capability). The main reason for this is that cache variables are primarily intended as a customization point for developers. Rather than hard-coding the value in the CMakeLists.txt file as a normal variable, a cache variable can be used so that the developer can override the value without having to edit the CMakeLists.txt file. The variable can be modified by interactive GUI tools or by scripts without having to change anything in the project itself.

5.4. 变量的潜在令人惊讶的行为

5.4. Potentially Surprising Behavior Of Variables

人们常常不太理解的一点是，普通变量和缓存变量是两个不同的东西。普通变量和缓存变量可以具有相同的名称，但保存不同的值。在这种情况下，CMake 在使用时将检索普通变量的值而不是缓存变量${myVar}。换句话说，普通变量优先于缓存变量。例外情况是，在设置缓存变量的值时，在以下情况下，任何同名的普通变量都会从当前作用域中删除（遵循下面进一步讨论的策略设置）：

A point that is often not well understood is that normal and cache variables are two separate things. It is possible to have a normal variable and a cache variable with the same name, but holding different values. In such cases, CMake will retrieve the normal variable’s value rather than the cache variable when using ${myVar}. Put another way, normal variables take precedence over cache variables. The exception to this is that when setting a cache variable’s value, any normal variable of the same name is removed from the current scope in the following situations (subject to policy settings discussed further below):

在上面的前两种情况下，这意味着第一次和后续 CMake 运行之间可能会出现不同的行为。在第一次运行中，缓存变量将不存在或没有定义的类型，但在后续运行中它将存在。因此，在第一次运行中，普通变量将被隐藏，但在后续运行中，则不会。一个例子应该有助于说明问题：

In the first two cases above, this means it is possible to get different behavior between the first and subsequent CMake runs. In the first run, the cache variable won’t exist or won’t have a defined type, but in subsequent runs it will. Therefore, in the first run, a normal variable would be hidden, but in subsequent runs, it would not. An example should help illustrate the problem:

set(myVar foo)                  # Local myVar
set(result ${myVar})            # result = foo
set(myVar bar CACHE STRING "")  # Cache myVar

set(result ${myVar})   # First run:       result = bar
                       # Subsequent runs: result = foo

set(myVar fred)
set(result ${myVar})   # result = fred

set(myVar foo)                  # Local myVar
set(result ${myVar})            # result = foo
set(myVar bar CACHE STRING "")  # Cache myVar

set(result ${myVar})   # First run:       result = bar
                       # Subsequent runs: result = foo

set(myVar fred)
set(result ${myVar})   # result = fred

第 7 章“使用子目录”和第 8 章“函数和宏”${myVar}进一步讨论了变量的作用域如何影响 返回的值。

Chapter 7, Using Subdirectories and Chapter 8, Functions And Macros contain further discussions of how a variable’s scope can influence the value that ${myVar} would return.

在 CMake 3.13 中， 的行为option()已更改，如果已存在同名的普通变量，则该命令不执行任何操作。这种更新的行为通常是开发人员直观地期望的。CMake 3.21 中的命令也进行了类似的更改set()，但请注意这两个命令的新行为存在以下差异：

In CMake 3.13, the behavior of option() was changed such that if a normal variable already exists with the same name, the command does nothing. This newer behavior is typically what developers intuitively expect. A similar change was made for the set() command in CMake 3.21, but note the following differences in the new behavior for both commands:

开发人员应注意这些不一致以及提供新行为的不同 CMake 版本。策略CMP0077并CMP0126控制实际行为（请参阅 第 12 章，策略以了解如何操纵这些行为）。

Developers should be mindful of these inconsistencies and the different CMake versions that provide the new behaviors. Policies CMP0077 and CMP0126 control the actual behavior (see Chapter 12, Policies for an understanding of how these can be manipulated).

缓存和非缓存变量之间的交互也可能导致其他潜在的意外行为。考虑以下三个命令：

The interaction between cache and non-cache variables can also lead to other potentially unexpected behavior. Consider the following three commands:

unset(foo)
set(foo)
set(foo "")

unset(foo)
set(foo)
set(foo "")

人们可能会想，${foo}在这三种情况中的任何一种之后，对 的求值总是会给出一个空字符串，但只有最后一种情况才能保证这样做。两者unset(foo)都set(foo)从当前作用域中删除非缓存变量。如果还有一个名为 的缓存变量foo，则该缓存变量将保持不变，并${foo}提供该缓存变量的值。从这个意义上说，unset(foo)和set(foo)两者都有效地取消了foo缓存变量的屏蔽（如果存在的话）。另一方面，set(foo "") 不会删除非缓存变量，它显式地将其设置为空值，因此${foo}无论是否还有名为 的缓存变量，都将始终评估为空字符串foo。因此，将变量设置为空字符串而不是删除它可能是实现开发人员意图的更可靠的方法。

One might be tempted to think that the evaluation of ${foo} would always give an empty string after any of these three cases, but only the last is guaranteed to do so. Both unset(foo) and set(foo) remove a non-cache variable from the current scope. If there is also a cache variable called foo, that cache variable is left alone and ${foo} would provide the value of that cache variable. In this sense, unset(foo) and set(foo) both effectively unmask the foo cache variable, if one exists. On the other hand, set(foo "") doesn’t remove a non-cache variable, it explicitly sets it to an empty value, so ${foo} will always then evaluate to an empty string regardless of whether there is also a cache variable called foo. Therefore, setting a variable to an empty string rather than removing it is likely to be the more robust way of achieving the developer’s intention.

对于项目可能需要获取缓存变量的值并忽略任何同名非缓存变量的罕见情况，CMake 3.13 添加了表单文档$CACHE{someVar}。除了临时调试之外，项目通常不应使用此功能，因为它打破了长期以来的预期，即普通变量将覆盖缓存中设置的值。

For those rare situations where a project may need to get the value of a cache variable and ignore any non-cache variable of the same name, CMake 3.13 added documentation for the $CACHE{someVar} form. Projects should not generally make use of this other than for temporary debugging, since it breaks with the long-established expectation that normal variables will override values set in the cache.

5.5. 操作缓存变量

5.5. Manipulating Cache Variables

使用set()和option()，项目可以为其开发人员构建一组有用的自定义点。可以打开或关闭构建的不同部分，可以设置外部包的路径，可以修改编译器和链接器的标志等等。后面的章节将介绍缓存变量的这些和其他用途，但首先，需要了解操作这些变量的方法。开发人员可以通过两种主要方法来执行此操作，即通过cmake命令行或使用 GUI 工具。

Using set() and option(), a project can build up a useful set of customization points for its developers. Different parts of the build can be turned on or off, paths to external packages can be set, flags for compilers and linkers can be modified and so on. Later chapters cover these and other uses of cache variables, but first, the ways to manipulate such variables need to be understood. There are two primary ways developers can do this, either from the cmake command line or using a GUI tool.

cmake -D myVar:type=someValue ...

cmake -D myVar:type=someValue ...

cmake -D foo:BOOL=ON ...
cmake -D "bar:STRING=这包含空格" ...
cmake -D hideMe=mysteryValue ...
cmake -D helpers:FILEPATH=subdir/helpers.txt ...
cmake -D helpDir:PATH=/opt/helpThings ...

cmake -D foo:BOOL=ON ...
cmake -D "bar:STRING=This contains spaces" ...
cmake -D hideMe=mysteryValue ...
cmake -D helpers:FILEPATH=subdir/helpers.txt ...
cmake -D helpDir:PATH=/opt/helpThings ...

cmake -U '帮助*' -U foo ...

cmake -U 'help*' -U foo ...

5.5.2. CMake 图形用户界面工具

5.5.2. CMake GUI Tools

通过命令行设置缓存变量是自动构建脚本以及通过cmake命令驱动 CMake 的其他任何内容的重要组成部分。然而，对于日常开发来说，CMake 提供的 GUI 工具通常能够提供更好的用户体验。CMake 提供了两个等效的 GUI 工具cmake-gui 和ccmake，允许开发人员交互地操作缓存变量。cmake-gui是所有主要桌面平台都支持的功能齐全的 GUI 应用程序，而ccmake使用基于curses 的界面，可以在纯文本环境（例如通过连接）中使用ssh。 cmake-gui包含在所有平台的官方 CMake 发行包中，ccmake包含在除 Windows 之外的所有平台上。如果在 Linux 上使用系统提供的软件包而不是官方版本，请注意许多发行版会分成cmake-gui自己的软件包。

Setting cache variables via the command line is an essential part of automated build scripts and anything else driving CMake via the cmake command. For everyday development, however, the GUI tools provided by CMake often present a better user experience. CMake provides two equivalent GUI tools, cmake-gui and ccmake, which allow developers to manipulate cache variables interactively. cmake-gui is a fully functional GUI application supported on all major desktop platforms, whereas ccmake uses a curses-based interface which can be used in text-only environments such as over a ssh connection. cmake-gui is included in the official CMake release packages for all platforms, ccmake is included for all platforms except Windows. If using system-provided packages on Linux rather than the official releases, note that many distributions split cmake-gui out into its own package.

用户cmake-gui界面如下图所示。顶部部分允许定义项目的源目录和构建目录。中间部分是可以查看和编辑缓存变量的地方。底部是Configure和Generate按钮，后面是显示这些操作的输出的日志区域。

The cmake-gui user interface is shown in the figure below. The top section allows the project’s source and build directories to be defined. The middle section is where the cache variables can be viewed and edited. At the bottom are the Configure and Generate buttons, followed by a log area that shows the output from those operations.

源目录必须设置为包含 CMakeLists.txt项目源树顶部的文件的目录。构建目录是 CMake 生成所有构建输出的位置（推荐的目录布局已在第 2 章“设置项目”中讨论）。对于新项目，两者都必须设置，但对于现有项目，设置构建目录也会更新源目录，因为源位置存储在构建目录的缓存中。

The source directory must be set to the directory containing the CMakeLists.txt file at the top of the project’s source tree. The build directory is where CMake will generate all build output (recommended directory layouts were discussed in Chapter 2, Setting Up A Project). For new projects, both must be set, but for existing projects, setting the build directory will also update the source directory, since the source location is stored in the build directory’s cache.

CMake 的两阶段设置过程在第 2.3 节“生成项目文件”中介绍。在第一阶段，CMakeLists.txt读取文件并在内存中构建项目的表示。这称为配置阶段。如果配置阶段成功，则可以执行生成阶段以在构建目录中创建构建工具的项目文件。cmake从命令行运行时 ，两个阶段都会自动执行，但在 GUI 应用程序中，它们是通过Configure和 Generate按钮单独触发的。每次启动配置步骤时，UI 中间显示的缓存变量都会更新。任何新添加的变量或上次运行中更改值的变量都将以红色突出显示（首次加载项目时，所有变量都会突出显示）。良好的做法是重新运行配置阶段，直到没有任何更改，因为这可以确保更复杂的项目的稳健行为，在这些项目中，启用某些选项可能会添加更多选项，这可能需要另一个配置阶段。一旦所有缓存变量都显示且没有红色突出显示，则可以运行生成阶段。上一个屏幕截图中的示例显示了配置阶段运行后的典型日志输出，并且未对任何缓存变量进行任何更改。

CMake’s two-stage setup process was introduced in Section 2.3, “Generating Project Files”. In the first stage, the CMakeLists.txt file is read and a representation of the project is built up in memory. This is called the configure stage. If the configure stage is successful, the generate stage can then be executed to create the build tool’s project files in the build directory. When running cmake from the command line, both stages are executed automatically, but in the GUI application, they are triggered separately with the Configure and Generate buttons. Each time the configure step is initiated, the cache variables shown in the middle of the UI are updated. Any variables which were newly added or which changed value from the previous run will be highlighted in red (when a project is first loaded, all variables are shown highlighted). Good practice is to re-run the configure stage until there are no changes, since this ensures robust behavior for more complex projects where enabling some options may add further options which could require another configure pass. Once all cache variables are shown without red highlighting, the generate stage can be run. The example in the previous screenshot shows typical log output after the configure stage has been run and no changes were made to any of the cache variables.

将鼠标悬停在任何缓存变量上将显示包含 docstring该变量的工具提示。新的缓存变量也可以使用按钮添加Add Entry，这相当于发出set()一个空的命令docstring。可以使用按钮删除缓存变量Remove Entry，尽管 CMake 很可能会在下次运行时重新创建该变量。

Hovering the mouse over any cache variable will show a tooltip containing the docstring for that variable. New cache variables can also be added with the Add Entry button, which is equivalent to issuing a set() command with an empty docstring. Cache variables can be removed with the Remove Entry button, although CMake will most likely recreate that variable on the next run.

单击变量可以在针对变量类型定制的小部件中编辑其值。布尔值显示为复选框，文件和路径有一个浏览文件系统按钮，字符串通常显示为文本行编辑。作为一种特殊情况，可以为类型的缓存变量STRING指定一组值，以在 CMake GUI 的组合框中显示，而不是显示简单的文本输入小部件。这是通过设置缓存变量的属性来实现的（第 9.6 节“缓存变量属性”STRINGS中有详细介绍，但为了方便起见，在此处显示）：

Clicking on a variable allows its value to be edited in a widget tailored to the variable type. Booleans are shown as a checkbox, files and paths have a browse filesystem button and strings are usually presented as a text line edit. As a special case, cache variables of type STRING can be given a set of values to show in a combobox in CMake GUI instead of showing a simple text entry widget. This is achieved by setting a cache variable’s STRINGS property (covered in detail in Section 9.6, “Cache Variable Properties”, but shown here for convenience):

set(trafficLight Green CACHE STRING "Status of something")
set_property(CACHE trafficLight PROPERTY
    STRINGS Red Orange Green
)

set(trafficLight Green CACHE STRING "Status of something")
set_property(CACHE trafficLight PROPERTY
    STRINGS Red Orange Green
)

在上面，trafficLight缓存变量最初的值为 Green。当用户尝试修改时trafficLight，cmake-gui他们将获得一个包含三个值的组合框Red，Orange而 Green不是一个简单的行编辑小部件，否则他们将允许他们输入任意文本。请注意，设置STRINGS变量的属性并不会阻止该变量分配其他值，它只会影响cmake-gui编辑它时使用的小部件。set()仍然可以通过文件中的命令 CMakeLists.txt或通过其他方式（例如手动编辑 文件）为变量指定其他值CMakeCache.txt。

In the above, the trafficLight cache variable will initially have the value Green. When the user attempts to modify trafficLight in cmake-gui, they will be given a combobox containing the three values Red, Orange and Green instead of a simple line edit widget which would otherwise have allowed them to enter any arbitrary text. Note that setting the STRINGS property on the variable doesn’t prevent that variable from having other values assigned to it, it only affects the widget used by cmake-gui when editing it. The variable can still be given other values via set() commands in the CMakeLists.txt file or by other means such as manually editing the CMakeCache.txt file.

缓存变量还可以具有将它们标记为高级或非高级的属性。这也只影响变量在 中的显示方式cmake-gui，它不会以任何方式影响 CMake 在处理过程中如何使用变量。默认情况下， cmake-gui仅显示非高级变量，通常仅显示开发人员有兴趣查看或修改的主要变量。启用该Advanced选项会显示除标记的变量之外的所有缓存变量 INTERNAL（查看变量的唯一方法INTERNAL是使用文本编辑器编辑 CMakeCache.txt文件，因为开发人员不打算直接操作它们）。mark_as_advanced()可以使用文件中的命令将变量标记为高级CMakeLists.txt：

Cache variables can also have a property marking them as advanced or not. This too only affects the way the variable is displayed in cmake-gui, it does not in any way affect how CMake uses the variable during processing. By default, cmake-gui only shows non-advanced variables, which typically presents just the main variables a developer would be interested in viewing or modifying. Enabling the Advanced option shows all cache variables except those marked INTERNAL (the only way to see INTERNAL variables is to edit the CMakeCache.txt file with a text editor, since they are not intended to be manipulated directly by developers). Variables can be marked as advanced with the mark_as_advanced() command within the CMakeLists.txt file:

mark_as_advanced([CLEAR|FORCE] var1 [var2...])

mark_as_advanced([CLEAR|FORCE] var1 [var2...])

关键字CLEAR确保变量不被标记为高级，而 FORCE关键字确保变量被标记为高级。如果没有任一关键字，则仅当变量尚未设置高级/非高级状态时，它们才会被标记为高级。

The CLEAR keyword ensures the variables are not marked as advanced, while the FORCE keyword ensures the variables are marked advanced. Without either keyword, the variables will only be marked as advanced if they don’t already have an advanced/non-advanced state set.

选择该Grouped选项可以根据变量名称的开头到第一个下划线将变量分组在一起，从而更轻松地查看高级变量。过滤显示的变量列表的另一种方法是在该Search区域中输入文本，这会导致仅显示名称或值中包含指定文本的变量。

Selecting the Grouped option can make viewing advanced variables easier by grouping variables together based on the start of the variable name up to the first underscore. Another way to filter the list of variables shown is to enter text in the Search area, which results in only showing variables with the specified text in their name or value.

当配置阶段在新项目上首次运行时，开发人员会看到一个类似于下一个屏幕截图中所示的对话框：

When the configure stage is run for the first time on a new project, the developer is presented with a dialog similar to that shown in the next screenshot:

此对话框是指定 CMake 生成器和工具链的位置。生成器的选择通常取决于开发人员的个人喜好，组合框中提供了可用选项。根据项目的不同，生成器的选择可能比组合框选项允许的限制更严格，例如，如果项目依赖于生成器特定的功能。一个常见的例子是，由于 Apple 平台的独特功能（例如代码签名和 iOS/tvOS/watchOS 支持），需要 Xcode 生成器的项目。一旦为项目选择了生成器，就无法在不删除缓存并重新启动的情况下更改它， File如果需要，可以从菜单中完成此操作。

This dialog is where the CMake generator and toolchain are specified. The choice of generator is usually up to the developer’s personal preference, with available options provided in the combobox. Depending on the project, the choice of generator may be more restricted than what the combobox options allow, such as if the project relies on generator-specific functionality. A common example of this is a project that requires the Xcode generator due to the Apple platform’s unique features, such as code signing and iOS/tvOS/watchOS support. Once a generator has been selected for a project, it cannot be changed without deleting the cache and starting again, which can be done from the File menu if required.

对于所提供的工具链选项，每一种都需要开发人员提供越来越多的信息。使用默认的本机编译器是普通桌面开发的常见选择，选择该选项不需要更多细节。如果需要更多控制，开发人员可以覆盖本机编译器，并在后续对话框中给出编译器的路径。如果有单独的工具链文件可用，那么它不仅可以用于自定义编译器，还可以用于自定义目标环境、编译器标志和各种其他内容。交叉编译时通常会使用工具链文件， 第 22 章工具链和交叉编译对此进行了详细介绍。最后，为了最终控制，开发人员可以指定交叉编译的全套选项，但不建议在正常使用中这样做。工具链文件可以提供相同的信息，但具有可以根据需要重复使用的优点。

For the toolchain options presented, each one requires progressively more information from the developer. Using the default native compilers is the usual choice for ordinary desktop development and selecting that option requires no further details. If more control is required, developers can instead override the native compilers, with the paths to the compilers being given in a follow-up dialog. If a separate toolchain file is available, that can be used to customize not just the compilers but also the target environment, compiler flags and various other things. Using a toolchain file is typical when cross-compiling, which is covered in detail in Chapter 22, Toolchains And Cross Compiling. Lastly, for ultimate control, developers can specify the full set of options for cross-compiling, but this is not recommended for normal use. A toolchain file can provide the same information but has the advantage that it can be re-used as needed.

该ccmake工具提供了与应用程序大部分相同的功能cmake-gui ，但它是通过基于文本的界面来实现的：

The ccmake tool offers most of the same functionality as the cmake-gui application, but it does so through a text-based interface:

不像使用那样选择源目录和构建目录 cmake-gui，而是必须在命令行上指定源目录或构建目录ccmake ，就像cmake命令一样。

Rather than selecting the source and build directories like with cmake-gui, the source or build directory has to be specified on the ccmake command line, just like for the cmake command.

该界面的一个小缺点ccmake是无法过滤显示的变量。编辑变量的方法也不如cmake-gui. 尽管如此，ccmake当完整的 cmake-gui应用程序不实用或不可用时（例如通过不支持 UI 转发的终端连接），该工具是一个有用的替代方案。

A minor drawback of the ccmake interface is that there is no ability to filter the variables shown. The methods for editing a variable are also not as rich as with cmake-gui. Nevertheless, the ccmake tool is a useful alternative when the full cmake-gui application is not practical or not available, such as over a terminal connection that cannot support UI forwarding.

5.6. 打印变量值

5.6. Printing Variable Values

随着项目变得更加复杂或在调查意外行为时，在 CMake 运行期间打印出诊断消息和变量值可能会很有用。这通常使用命令来实现，第 13 章“调试和诊断”message()中详细介绍了该命令。现在，只要知道最简单的形式，该 命令所做的就是将其参数打印到 CMake 的输出中就足够了。如果给出多个参数，它不会在参数之间添加分隔符，并且换行符会自动附加到消息末尾。还可以使用通用符号显式包含换行符。可以使用通常的 符号将变量的值包含在消息中。message()\n${myVar}

As projects get more complicated or when investigating unexpected behavior, it can be useful to print out diagnostic messages and variable values during a CMake run. This is generally achieved using the message() command, which is covered in detail in Chapter 13, Debugging And Diagnostics. For now, it is enough to know that in its simplest form, all the message() command does is print its arguments to CMake’s output. It adds no separator between arguments if more than one argument is given and a newline is automatically appended to the end of the message. Newlines can also be explicitly included using the common \n notation. A variable’s value can be included in the message by using the usual ${myVar} notation.

set(myVar HiThere)
message("The value of myVar = ${myVar}\nAnd this "
        "appears on the next line")

set(myVar HiThere)
message("The value of myVar = ${myVar}\nAnd this "
        "appears on the next line")

这将给出以下输出：

This will give the following output:

myVar 的值 = HiThere
这出现在下一行

The value of myVar = HiThere
And this appears on the next line

5.7. 字符串处理

5.7. String Handling

随着项目复杂性的增加，在许多情况下，需要实现更多复杂的变量管理逻辑。CMake 为此提供的一个核心工具是string()命令，它提供了广泛有用的字符串处理功能。该命令使项目能够执行查找和替换操作、正则表达式匹配、大小写转换、去除空格和其他常见任务。下面介绍了一些更常用的功能，但 CMake 参考文档应被视为所有可用操作及其行为的规范来源。

As project complexity grows, in many cases so too does the need to implement more involved logic for how variables are managed. A core tool CMake provides for this is the string() command, which provides a wide range of useful string handling functionality. This command enables projects to perform find and replace operations, regular expression matching, upper/lower case transformations, strip whitespace and other common tasks. Some of the more frequently used functionality is presented below, but the CMake reference documentation should be considered the canonical source of all available operations and their behavior.

第一个参数string()定义要执行的操作，后续参数取决于所请求的操作。这些参数通常需要至少一个输入字符串，并且由于 CMake 命令无法返回值，即操作结果的输出变量。在下面的材料中，该输出变量通常被命名为outVar。

The first argument to string() defines the operation to be performed and subsequent arguments depend on the operation being requested. These arguments will generally require at least one input string and since CMake commands cannot return a value, an output variable for the result of the operation. In the material below, this output variable will generally be named outVar.

string(FIND inputString subString outVar [REVERSE])

string(FIND inputString subString outVar [REVERSE])

FIND搜索subStringin并存储找到的inputString索引（第一个字符是索引 0）。除非指定，否则将查找第一个出现的位置，在这种情况下，将查找最后一个出现的位置。如果中没有出现 ，则将赋予值-1。subStringoutVarREVERSEsubStringinputStringoutVar

FIND searches for subString in inputString and stores the index of the found subString in outVar (the first character is index 0). The first occurrence is found unless REVERSE is specified, in which case the last occurrence will be found instead. If subString does not appear in inputString, then outVar will be given the value -1.

string(FIND abcdefabcdef def fwdIndex)
string(FIND abcdefabcdef def revIndex REVERSE)

message("fwdIndex = ${fwdIndex}\n"
        "revIndex = ${revIndex}")

string(FIND abcdefabcdef def fwdIndex)
string(FIND abcdefabcdef def revIndex REVERSE)

message("fwdIndex = ${fwdIndex}\n"
        "revIndex = ${revIndex}")

这会产生以下输出：

This results in the following output:

前向索引 = 3
转速指数 = 9

fwdIndex = 3
revIndex = 9

替换简单子字符串遵循类似的模式：

Replacing a simple substring follows a similar pattern:

string(REPLACE matchString replaceWith outVar input...)

string(REPLACE matchString replaceWith outVar input...)

该操作会将字符串中 REPLACE每次出现的 替换为 ，并将结果存储在 中。当给出多个字符串时，在搜索替换之前，它们将连接在一起，每个字符串之间不使用任何分隔符。这有时会导致意外的匹配，并且通常开发人员在大多数情况下只会提供一个字符串。matchStringinputreplaceWithoutVarinputinput

The REPLACE operation will replace every occurrence of matchString in the input strings with replaceWith and store the result in outVar. When multiple input strings are given, they are joined together without any separator between each string before searching for substitutions. This can sometimes lead to unexpected matches and typically developers would provide just the one input string in most situations.

该操作也很好地支持正则表达式REGEX，根据第二个参数确定有一些不同的可用变体：

Regular expressions are also well supported by the REGEX operation, with a few different variants available as determined by the second argument:

string(REGEX MATCH    regex outVar input...)
string(REGEX MATCHALL regex outVar input...)
string(REGEX REPLACE  regex replaceWith outVar input...)

string(REGEX MATCH    regex outVar input...)
string(REGEX MATCHALL regex outVar input...)
string(REGEX REPLACE  regex replaceWith outVar input...)

匹配的正则表达式 ,regex可以使用典型的基本正则表达式语法（有关完整规范，请参阅 CMake 参考文档），但不支持某些常见功能（例如否定）。字符串input在替换之前连接。该 MATCH操作仅找到第一个匹配项并将其存储在outVar. MATCHALL查找所有匹配项并将它们存储为outVar列表。REPLACE 将返回整个input字符串，每个匹配项都替换为 replaceWith。可以replaceWith使用常用符号 \1、\2 等来引用匹配项，但请注意，除非使用括号符号，否则反斜杠本身必须转义。以下示例及其输出演示了上述几点：

The regular expression to match, regex, can make use of typical basic regular expression syntax (see the CMake reference documentation for the full specification), although some common features such as negation are not supported. The input strings are concatenated before substitution. The MATCH operation finds just the first match and stores it in outVar. MATCHALL finds all matches and stores them in outVar as a list. REPLACE will return the entire input string with each match replaced by replaceWith. Matches can be referred to in replaceWith using the usual notation \1, \2, etc., but note that the backslashes themselves must be escaped unless bracket notation is used. The following example and its output demonstrate the above points:

string(REGEX MATCH "[ace]"
    matchOne abcdefabcdef
)
string(REGEX MATCHALL "[ace]"
    matchAll abcdefabcdef
)
string(REGEX REPLACE "([de])" "X\\1Y"
    replVar1 abc def abcdef
)
string(REGEX REPLACE "([de])" [[X\1Y]]
    replVar2 abcdefabcdef
)

message("matchOne = ${matchOne}\n"
        "matchAll = ${matchAll}\n"
        "replVar1 = ${replVar1}\n"
        "replVar2 = ${replVar2}")

string(REGEX MATCH "[ace]"
    matchOne abcdefabcdef
)
string(REGEX MATCHALL "[ace]"
    matchAll abcdefabcdef
)
string(REGEX REPLACE "([de])" "X\\1Y"
    replVar1 abc def abcdef
)
string(REGEX REPLACE "([de])" [[X\1Y]]
    replVar2 abcdefabcdef
)

message("matchOne = ${matchOne}\n"
        "matchAll = ${matchAll}\n"
        "replVar1 = ${replVar1}\n"
        "replVar2 = ${replVar2}")

匹配一个 = a
全部匹配 = a;c;e;a;c;e
replVar1 = abcXdYXeYfabcXdYXeYf
replVar2 = abcXdYXeYfabcXdYXeYf

matchOne = a
matchAll = a;c;e;a;c;e
replVar1 = abcXdYXeYfabcXdYXeYf
replVar2 = abcXdYXeYfabcXdYXeYf

提取子字符串也是可能的：

Extracting a substring is also possible:

string(SUBSTRING input index length outVar)

string(SUBSTRING input index length outVar)

是index一个整数，定义要从中提取的子字符串的开头 input。length将提取最多字符，或者如果length为-1，则返回的子字符串将包含直到字符串末尾的所有字符input 。length 请注意，在 CMake 3.1 及更早版本中，如果指向字符串末尾，则会报告错误。

The index is an integer defining the start of the substring to extract from input. Up to length characters will be extracted, or if length is -1, the returned substring will contain all characters up to the end of the input string. Note that in CMake 3.1 and earlier, an error was reported if length pointed past the end of the string.

可以轻松获得字符串长度，并且可以轻松地将字符串转换为大写或小写。从字符串的开头和结尾去除空格也很简单。这些操作的语法都具有相同的形式：

String length can be trivially obtained and strings can easily be converted to upper or lower case. It is also straightforward to strip whitespace from the start and end of a string. The syntax for these operations all share the same form:

string(LENGTH  input outVar)
string(TOLOWER input outVar)
string(TOUPPER input outVar)
string(STRIP   input outVar)

string(LENGTH  input outVar)
string(TOLOWER input outVar)
string(TOUPPER input outVar)
string(STRIP   input outVar)

在 的情况下LENGTH，由于历史原因，该命令计算字节而不是字符。对于包含多字节字符的字符串，这意味着报告的长度将与字符数不同。

In the case of LENGTH, for historical reasons the command counts bytes rather than characters. For strings containing multi-byte characters, this means the reported length will be different to the number of characters.

CMake 提供其他操作，例如字符串比较、散列、时间戳、JSON 处理等，但它们在日常 CMake 项目中使用不太常见。感兴趣的读者应查阅该 string()命令的 CMake 参考文档以了解完整的详细信息。

CMake provides other operations, such as string comparison, hashing, timestamps, JSON handling and more, but their use is less common in everyday CMake projects. The interested reader should consult the CMake reference documentation for the string() command for full details.

5.8. 列表

5.8. Lists

列表在 CMake 中大量使用。最终，列表只是一个由分号分隔的列表项的字符串（有一个例外，该情况将在 下面的第5.8.1 节“不平衡方括号的问题”中介绍）。这会使操作单个列表项变得不太方便。CMake 提供了list()命令来促进此类任务。与string()命令一样，list()期望操作作为其第一个参数执行。a;b;c第二个参数始终是要操作的列表，并且它必须是变量（即不允许传递原始列表）。

Lists are used heavily in CMake. Ultimately, lists are just a single string with list items separated by semicolons (with one exception, which is covered in Section 5.8.1, “Problems With Unbalanced Square Brackets” further below). This can make it less convenient to manipulate individual list items. CMake provides the list() command to facilitate such tasks. Like for the string() command, list() expects the operation to perform as its first argument. The second argument is always the list to operate on and it must be a variable (i.e. passing a raw list like a;b;c is not permitted).

最基本的列表操作是计算项目数并从列表中检索一个或多个项目：

The most basic list operations are counting the number of items and retrieving one or more items from the list:

list(LENGTH listVar outVar)
list(GET    listVar index [index...] outVar)

list(LENGTH listVar outVar)
list(GET    listVar index [index...] outVar)

用法示例：

Example usage:

set(myList a b c)        # Creates the list "a;b;c"

list(LENGTH myList len)
message("length  = ${len}")

list(GET myList 2 1 letters)
message("letters = ${letters}")

set(myList a b c)        # Creates the list "a;b;c"

list(LENGTH myList len)
message("length  = ${len}")

list(GET myList 2 1 letters)
message("letters = ${letters}")

上面示例的输出将是：

The output of the above example would be:

长度=3
字母=c;b

length  = 3
letters = c;b

插入、追加和前置项目也是一项常见任务：

Inserting, appending and prepending items is also a common task:

list(INSERT  listVar index item [item...])
list(APPEND  listVar item [item...])

# Requires CMake 3.15 or later
list(PREPEND listVar item [item...])

list(INSERT  listVar index item [item...])
list(APPEND  listVar item [item...])

# Requires CMake 3.15 or later
list(PREPEND listVar item [item...])

LENGTH与和 的GET情况不同， INSERT、APPEND和PREPEND直接作用于listVar并就地修改它，如以下示例所示：

Unlike the LENGTH and GET cases, INSERT, APPEND and PREPEND act directly on the listVar and modify it in-place, as demonstrated by the following example:

set(myList a b c)

list(INSERT myList 2 X Y Z)
message("myList (first)  = ${myList}")

list(APPEND myList d e f)
message("myList (second) = ${myList}")

list(PREPEND myList P Q R)
message("myList (third)  = ${myList}")

set(myList a b c)

list(INSERT myList 2 X Y Z)
message("myList (first)  = ${myList}")

list(APPEND myList d e f)
message("myList (second) = ${myList}")

list(PREPEND myList P Q R)
message("myList (third)  = ${myList}")

给出以下输出：

Which gives the following output:

myList（第一个）= a;b;X;Y;Z;c
myList（第二个）= a;b;X;Y;Z;c;d;e;f
myList（第三个）= P;Q;R;a;b;X;Y;Z;c;d;e;f

myList (first)  = a;b;X;Y;Z;c
myList (second) = a;b;X;Y;Z;c;d;e;f
myList (third)  = P;Q;R;a;b;X;Y;Z;c;d;e;f

在列表中查找特定项目遵循预期模式：

Finding a particular item in the list follows the expected pattern:

list(FIND myList value outVar)

list(FIND myList value outVar)

用法示例：

Example usage:

set(myList a b c d e)
list(FIND myList d index)
message("index = ${index}")

set(myList a b c d e)
list(FIND myList d index)
message("index = ${index}")

结果输出：

Resultant output:

索引 = 3

index = 3

提供了三种删除项目的操作，所有这些操作都直接修改列表：

Three operations are provided for removing items, all of which modify the list directly:

list(REMOVE_ITEM       myList value [value...])
list(REMOVE_AT         myList index [index...])
list(REMOVE_DUPLICATES myList)

list(REMOVE_ITEM       myList value [value...])
list(REMOVE_AT         myList index [index...])
list(REMOVE_DUPLICATES myList)

该REMOVE_ITEM操作可用于从列表中删除一项或多项的所有实例。如果该项目不在列表中，则不是错误。 REMOVE_AT另一方面，指定要删除的一个或多个索引，如果任何指定索引超出列表末尾，CMake 将停止并出现错误。 REMOVE_DUPLICATES将确保列表仅包含唯一的项目。

The REMOVE_ITEM operation can be used to remove all instances of one or more items from a list. If the item is not in the list, it is not an error. REMOVE_AT on the other hand, specifies one or more indices to remove and CMake will halt with an error if any of the specified indices are past the end of the list. REMOVE_DUPLICATES will ensure the list contains only unique items.

CMake 3.15 添加了对从列表前面或后面弹出项目并可选择存储弹出项目的支持：

CMake 3.15 added support for popping items from the front or back of a list and optionally storing the popped items:

# Requires CMake 3.15 or later
list(POP_FRONT myList [outVar1 [outVar2...]])
list(POP_BACK myList [outVar1 [outVar2...]])

# Requires CMake 3.15 or later
list(POP_FRONT myList [outVar1 [outVar2...]])
list(POP_BACK myList [outVar1 [outVar2...]])

当没有outVar给出时，单个项目将从前面或后面弹出并丢弃。如果outVar给出一个或多个名称，弹出的项目将存储在这些变量中，弹出的项目数等于提供的变量名称的数量。

When no outVar is given, a single item is popped from the front or back and discarded. If one or more outVar names are given, popped items will be stored in those variables, with the number of items popped equal to the number of variable names provided.

列表项也可以使用REVERSE或SORT操作重新排序：

List items can also be reordered with REVERSE or SORT operations:

list(REVERSE myList)
list(SORT myList
    [COMPARE method]
    [CASE case]
    [ORDER order]
)

list(REVERSE myList)
list(SORT myList
    [COMPARE method]
    [CASE case]
    [ORDER order]
)

所有可选关键字list(SORT)仅适用于 CMake 3.13 或更高版本。如果COMPARE存在该选项，则method必须是以下之一：

All of the optional keywords for list(SORT) are only available with CMake 3.13 or later. If the COMPARE option is present, the method must be one of the following:

关键字CASE需要SENSITIVEor INSENSITIVEfor the case，而ORDER关键字需要ASCENDINGor DESCENDINGfor the order。

The CASE keyword requires SENSITIVE or INSENSITIVE for the case, while the ORDER keyword requires either ASCENDING or DESCENDING for the order.

对于所有采用索引的列表操作，负索引表示从列表末尾开始计数。以这种方式使用时，列表中的最后一项的索引为 -1，倒数第二项的索引为 -2，依此类推。

For all list operations taking an index, a negative index indicates that counting starts from the end of the list. When used this way, the last item in the list has index -1, the second last -2, and so on.

上面描述了大多数可用的list()子命令。除非另有说明，否则至少从 CMake 3.0 起所有提到的内容都受到支持，因此项目通常应该能够期望它们可用。有关支持的子命令的完整列表，读者应查阅 CMake 文档。

The above describes most of the available list() sub-commands. Those mentioned are all supported since at least CMake 3.0 unless otherwise noted, so projects should generally be able to expect them to be available. For the full list of supported sub-commands, the reader should consult the CMake documentation.

set(noBrackets   "a_a" "b_b")
set(withBrackets "a[a" "b]b")

list(LENGTH noBrackets   lenNo)
list(LENGTH withBrackets lenWith)

list(GET noBrackets   0 firstNo)
list(GET withBrackets 0 firstWith)

message("No brackets:   "
        "Length=${lenNo} --> First_element=${firstNo}"
)
message("With brackets: "
        "Length=${lenWith} --> First_element=${firstWith}"
)

set(noBrackets   "a_a" "b_b")
set(withBrackets "a[a" "b]b")

list(LENGTH noBrackets   lenNo)
list(LENGTH withBrackets lenWith)

list(GET noBrackets   0 firstNo)
list(GET withBrackets 0 firstWith)

message("No brackets:   "
        "Length=${lenNo} --> First_element=${firstNo}"
)
message("With brackets: "
        "Length=${lenWith} --> First_element=${firstWith}"
)

无括号：长度=2 --> First_element=a_a
带括号： Length=1 --> First_element=a[a;b]b

No brackets:   Length=2 --> First_element=a_a
With brackets: Length=1 --> First_element=a[a;b]b

5.9. 数学

5.9. Math

变量操作的另一种常见形式是数学计算。CMake 提供了math()用于执行基本数学评估的命令：

One other common form of variable manipulation is math computation. CMake provides the math() command for performing basic mathematical evaluation:

math(EXPR outVar mathExpr [OUTPUT_FORMAT format])

math(EXPR outVar mathExpr [OUTPUT_FORMAT format])

第一个参数必须是关键字EXPR，同时mathExpr定义要计算的表达式，结果将存储在outVar. 该表达式可以使用以下任何运算符，它们的含义与 C 代码中的含义相同：+ - * / % | & ^ ~ << >>。括号也受支持并具有其通常的数学含义。mathExpr可以使用通常的符号来引用变量${myVar} 。

The first argument must be the keyword EXPR, while mathExpr defines the expression to be evaluated and the result will be stored in outVar. The expression may use any of the following operators which all have the same meaning as they would in C code: + - * / % | & ^ ~ << >>. Parentheses are also supported and have their usual mathematical meaning. Variables can be referenced in the mathExpr with the usual ${myVar} notation.

如果使用 CMake 3.13 或更高版本，OUTPUT_FORMAT可以给出关键字来控制结果如何存储在outVar. format应该是，这DECIMAL是默认行为，或者 HEXADECIMAL。

If using CMake 3.13 or later, the OUTPUT_FORMAT keyword can be given to control how the result is stored in outVar. The format should be either DECIMAL, which is the default behavior, or HEXADECIMAL.

set(x 3)
set(y 7)
math(EXPR zDec "(${x}+${y}) * 2")
message("decimal = ${zDec}")

# Requires CMake 3.13 or later for HEXADECIMAL
math(EXPR zHex "(${x}+${y}) * 2" OUTPUT_FORMAT HEXADECIMAL)
message("hexadecimal = ${zHex}")

set(x 3)
set(y 7)
math(EXPR zDec "(${x}+${y}) * 2")
message("decimal = ${zDec}")

# Requires CMake 3.13 or later for HEXADECIMAL
math(EXPR zHex "(${x}+${y}) * 2" OUTPUT_FORMAT HEXADECIMAL)
message("hexadecimal = ${zHex}")

以上产生以下输出：

The above produces the following output:

小数 = 20
十六进制 = 0x14

decimal = 20
hexadecimal = 0x14

5.10. 推荐做法

5.10. Recommended Practices

在开发环境允许的情况下，CMake GUI 工具是一种快速、轻松地了解项目的构建选项并在开发过程中根据需要修改它们的有用方法。花一点时间熟悉它可以简化以后处理更复杂的项目。它还为开发人员提供了良好的工作基础，以便他们需要尝试编译器设置等内容，因为这些内容可以在 GUI 环境中轻松找到和修改。

Where the development environment allows it, the CMake GUI tool is a useful way to quickly and easily understand the build options for a project and to modify them as needed during development. A little bit of time spent getting familiar with it will simplify working with more complex projects later. It also gives developers a good base to work from should they need to experiment with things like compiler settings, since these are easily found and modified within the GUI environment.

更喜欢提供缓存变量来控制是否启用构建的可选部分，而不是在 CMake 之外的构建脚本中编码逻辑。这使得在 CMake GUI 和其他了解如何使用 CMake 缓存的工具中打开和关闭它们变得微不足道（越来越多的 IDE 环境正在获取此功能）。

Prefer to provide cache variables for controlling whether to enable optional parts of the build instead of encoding the logic in build scripts outside of CMake. This makes it trivial to turn them on and off in the CMake GUI and other tools which understand how to work with the CMake cache (a growing number of IDE environments are acquiring this capability).

除了可能普遍存在PATH或类似的操作系统级变量之外，尽量避免依赖于定义的环境变量。构建应该是可预测的、可靠的且易于设置，但如果它依赖于设置的环境变量才能正常工作，那么这可能会成为新开发人员在努力设置构建环境时感到沮丧的地方。此外，与调用构建本身时相比，运行 CMake 时的环境可能会发生变化。因此，尽可能通过缓存变量将信息直接传递给 CMake。

Try to avoid relying on environment variables being defined, apart from perhaps the ubiquitous PATH or similar operating system level variables. The build should be predictable, reliable and easy to set up, but if it relies on environment variables being set for things to work correctly, this can be a point of frustration for new developers as they wrestle to get their build environment set up. Furthermore, the environment at the time CMake is run can change compared to when the build itself is invoked. Therefore, prefer to pass information directly to CMake through cache variables instead wherever possible.

尝试尽早建立变量命名约定。对于缓存变量，请考虑将相关变量分组在公共前缀下，后跟下划线，以利用 CMake GUI 自动根据相同前缀对变量进行分组的方式。还要考虑到该项目有一天可能会成为某个较大项目的子部分，因此可能需要以项目名称开头的名称或与项目密切相关的名称。

Try to establish a variable naming convention early. For cache variables, consider grouping related variables under a common prefix followed by an underscore to take advantage of how CMake GUI groups variables based on the same prefix automatically. Also consider that the project may one day become a sub-part of some larger project, so a name beginning with the project name or something closely associated with the project may be desirable.

尽量避免在项目中定义与缓存变量同名的非缓存变量。对于刚接触 CMake 的开发人员来说，两种类型的变量之间的交互可能是意想不到的。后面的章节还重点介绍了与缓存变量同名的常规变量的其他常见错误和误用。

Try to avoid defining non-cache variables in the project which have the same name as cache variables. The interaction between the two types of variables can be unexpected for developers new to CMake. Later chapters also highlight other common errors and misuses of regular variables that share the same name as cache variables.

CMake 提供了大量预定义变量，这些变量提供有关系统的详细信息或影响 CMake 行为的某些方面。其中一些变量被项目大量使用，例如那些仅在为特定平台构建时定义的变量（WIN32、APPLE、UNIX等）。因此，建议开发人员偶尔快速浏览一下列出预定义变量的 CMake 文档页面，以帮助熟悉可用的内容。

CMake provides a large number of pre-defined variables that provide details about the system or influence certain aspects of CMake’s behavior. Some of these variables are heavily used by projects, such as those that are only defined when building for a particular platform (WIN32, APPLE, UNIX, etc.). It is therefore recommended for developers to occasionally make a quick scan through the CMake documentation page listing the pre-defined variables to help become familiar with what is available.

6.1. if() 命令

6.1. The if() Command

该if()命令的现代形式如下（elseif() 可以提供多个子句）：

The modern form of the if() command is as follows (multiple elseif() clauses can be provided):

if(expression1)
    # commands ...
elseif(expression2)
    # commands ...
else()
    # commands ...
endif()

if(expression1)
    # commands ...
elseif(expression2)
    # commands ...
else()
    # commands ...
endif()

CMake 的早期版本需要expression1重复作为else()andendif()子句的参数，但自 CMake 2.8.0 以来不再需要这样做。虽然使用旧形式的项目和示例代码仍然很常见，但不鼓励在新项目中使用它，因为它可能会有些难以阅读。新项目应将else()和 endif()参数留空，如上所示。

Very early versions of CMake required expression1 to be repeated as an argument to the else() and endif() clauses, but this has not been required since CMake 2.8.0. While it is still not unusual to encounter projects and example code using that older form, it is discouraged for new projects since it can be somewhat confusing to read. New projects should leave the else() and endif() arguments empty, as shown above.

if()和命令中的表达式elseif()可以采用多种不同的形式。CMake 提供传统的布尔逻辑以及各种其他条件，例如文件系统测试、版本比较和事物存在性测试。

The expressions in if() and elseif() commands can take a variety of different forms. CMake offers the traditional boolean logic as well as various other conditions such as file system tests, version comparison and testing for the existence of things.

if(value)

if(value)

# Examples of quoted and unquoted constants
if(YES)
if("True")
if(0)
if(TRUE)

# These are also treated as unquoted constants because the
# variable evaluation occurs before if() sees the values
set(A YES)
set(B 0)
if(${A})  # Evaluates to true
if(${B})  # Evaluates to false

# Does not match any of the true or false constants, so
# proceed to testing as a variable name in the fall-through
# case below
if(someLetters)

# Quoted value that doesn't match any of the true or false
# constants, so again fall through to testing as a variable
# name or string
if("someLetters")

# Examples of quoted and unquoted constants
if(YES)
if("True")
if(0)
if(TRUE)

# These are also treated as unquoted constants because the
# variable evaluation occurs before if() sees the values
set(A YES)
set(B 0)
if(${A})  # Evaluates to true
if(${B})  # Evaluates to false

# Does not match any of the true or false constants, so
# proceed to testing as a variable name in the fall-through
# case below
if(someLetters)

# Quoted value that doesn't match any of the true or false
# constants, so again fall through to testing as a variable
# name or string
if("someLetters")

if(<variable|string>)

if(<variable|string>)

# Common pattern, often used with variables defined
# by commands such as option(enableSomething "...")
if(enableSomething)
    # ...
endif()

# Common pattern, often used with variables defined
# by commands such as option(enableSomething "...")
if(enableSomething)
    # ...
endif()

# Logical operators
if(NOT expression)
if(expression1 AND expression2)
if(expression1 OR expression2)

# Example with parentheses
if(NOT (expression1 AND (expression2 OR expression3)))

# Logical operators
if(NOT expression)
if(expression1 AND expression2)
if(expression1 OR expression2)

# Example with parentheses
if(NOT (expression1 AND (expression2 OR expression3)))

if(value1 OPERATOR value2)

if(value1 OPERATOR value2)

# Valid numeric expressions, all evaluating as true
if(2 GREATER 1)
if("23" EQUAL 23)
set(val 42)
if(${val} EQUAL 42)
if("${val}" EQUAL 42)

# Invalid expression that evaluates as true with at
# least some CMake versions. Do not rely on this behavior.
if("23a" EQUAL 23)

# Valid numeric expressions, all evaluating as true
if(2 GREATER 1)
if("23" EQUAL 23)
set(val 42)
if(${val} EQUAL 42)
if("${val}" EQUAL 42)

# Invalid expression that evaluates as true with at
# least some CMake versions. Do not rely on this behavior.
if("23a" EQUAL 23)

if(1.2   VERSION_EQUAL   1.2.0)
if(1.2   VERSION_LESS    1.2.3)
if(1.2.3 VERSION_GREATER 1.2  )
if(2.0.1 VERSION_GREATER 1.9.7)
if(1.8.2 VERSION_LESS    2    )

if(1.2   VERSION_EQUAL   1.2.0)
if(1.2   VERSION_LESS    1.2.3)
if(1.2.3 VERSION_GREATER 1.2  )
if(2.0.1 VERSION_GREATER 1.9.7)
if(1.8.2 VERSION_LESS    2    )

if(value MATCHES regex)

if(value MATCHES regex)

if("Hi from ${who}" MATCHES "Hi from (Fred|Barney).*")
    message("${CMAKE_MATCH_1} says hello")
endif()

if("Hi from ${who}" MATCHES "Hi from (Fred|Barney).*")
    message("${CMAKE_MATCH_1} says hello")
endif()

if(EXISTS pathToFileOrDir)
if(IS_DIRECTORY pathToDir)
if(IS_SYMLINK fileName)
if(IS_ABSOLUTE path)
if(file1 IS_NEWER_THAN file2)

if(EXISTS pathToFileOrDir)
if(IS_DIRECTORY pathToDir)
if(IS_SYMLINK fileName)
if(IS_ABSOLUTE path)
if(file1 IS_NEWER_THAN file2)

set(firstFile  "/full/path/to/somewhere")
set(secondFile "/full/path/to/another/file")

if(NOT EXISTS ${firstFile})
    message(FATAL_ERROR "${firstFile} is missing")
elseif(NOT EXISTS ${secondFile} OR
       NOT ${secondFile} IS_NEWER_THAN ${firstFile})
    # ... commands to recreate secondFile
endif()

set(firstFile  "/full/path/to/somewhere")
set(secondFile "/full/path/to/another/file")

if(NOT EXISTS ${firstFile})
    message(FATAL_ERROR "${firstFile} is missing")
elseif(NOT EXISTS ${secondFile} OR
       NOT ${secondFile} IS_NEWER_THAN ${firstFile})
    # ... commands to recreate secondFile
endif()

# WARNING: Very likely to be wrong
if(${firstFile} IS_NEWER_THAN ${secondFile})
    # ... commands to recreate secondFile
endif()

# WARNING: Very likely to be wrong
if(${firstFile} IS_NEWER_THAN ${secondFile})
    # ... commands to recreate secondFile
endif()

if(DEFINED name)
if(COMMAND name)
if(POLICY name)
if(TARGET name)
if(TEST name)   # Available from CMake 3.4 onward

if(DEFINED name)
if(COMMAND name)
if(POLICY name)
if(TARGET name)
if(TEST name)   # Available from CMake 3.4 onward

if(value IN_LIST listVar)  # Available since CMake 3.3

if(value IN_LIST listVar)  # Available since CMake 3.3

if(WIN32)
    set(platformImpl source_win.cpp)
else()
    set(platformImpl source_generic.cpp)
endif()

if(WIN32)
    set(platformImpl source_win.cpp)
else()
    set(platformImpl source_generic.cpp)
endif()

if(MSVC)
    set(platformImpl source_msvc.cpp)
else()
    set(platformImpl source_generic.cpp)
endif()

if(MSVC)
    set(platformImpl source_msvc.cpp)
else()
    set(platformImpl source_generic.cpp)
endif()

if(APPLE)
    # Some Xcode-specific settings here...
else()
    # Things for other platforms here...
endif()

if(APPLE)
    # Some Xcode-specific settings here...
else()
    # Things for other platforms here...
endif()

if(CMAKE_GENERATOR STREQUAL "Xcode")
    # Some Xcode-specific settings here...
else()
    # Things for other CMake generators here...
endif()

if(CMAKE_GENERATOR STREQUAL "Xcode")
    # Some Xcode-specific settings here...
else()
    # Things for other CMake generators here...
endif()

option(BUILD_MYLIB "Enable building the MyLib target")
if(BUILD_MYLIB)
    add_library(MyLib src1.cpp src2.cpp)
endif()

option(BUILD_MYLIB "Enable building the MyLib target")
if(BUILD_MYLIB)
    add_library(MyLib src1.cpp src2.cpp)
endif()

6.2. 循环播放

6.2. Looping

许多 CMake 项目中的另一个常见需求是对项目列表或一系列值执行某些操作。或者，可能需要重复执行某些操作，直到满足特定条件。CMake 很好地满足了这些需求，提供了传统行为和一些附加功能，使使用 CMake 功能变得更加容易。

Another common need in many CMake projects is to perform some action on a list of items or for a range of values. Alternatively, some action may need to be performed repeatedly until a particular condition is met. These needs are well covered by CMake, offering the traditional behavior with some additions to make working with CMake features a little easier.

foreach(loopVar arg1 arg2 ...)
    # ...
endforeach()

foreach(loopVar arg1 arg2 ...)
    # ...
endforeach()

foreach(loopVar IN [LISTS listVar1 ...] [ITEMS item1 ...])
    # ...
endforeach()

foreach(loopVar IN [LISTS listVar1 ...] [ITEMS item1 ...])
    # ...
endforeach()

set(list1 A B)
set(list2)
set(foo WillNotBeShown)
foreach(loopVar IN LISTS list1 list2 ITEMS foo bar)
    message("Iteration for: ${loopVar}")
endforeach()

set(list1 A B)
set(list2)
set(foo WillNotBeShown)
foreach(loopVar IN LISTS list1 list2 ITEMS foo bar)
    message("Iteration for: ${loopVar}")
endforeach()

迭代：A
迭代：B
迭代： foo
迭代：酒吧

Iteration for: A
Iteration for: B
Iteration for: foo
Iteration for: bar

foreach(loopVar... IN ZIP_LISTS listVar...)
    # ...
endforeach()

foreach(loopVar... IN ZIP_LISTS listVar...)
    # ...
endforeach()

set(list0 A B)
set(list1 one two)

foreach(var0 var1 IN ZIP_LISTS list0 list1)
    message("Vars: ${var0} ${var1}")
endforeach()

foreach(var IN ZIP_LISTS list0 list1)
    message("Vars: ${var_0} ${var_1}")
endforeach()

set(list0 A B)
set(list1 one two)

foreach(var0 var1 IN ZIP_LISTS list0 list1)
    message("Vars: ${var0} ${var1}")
endforeach()

foreach(var IN ZIP_LISTS list0 list1)
    message("Vars: ${var_0} ${var_1}")
endforeach()

变量：一
变量：B 2

Vars: A one
Vars: B two

set(long  A B C)
set(short justOne)

foreach(varLong varShort IN ZIP_LISTS long short)
    message("Vars: ${varLong} ${varShort}")
endforeach()

set(long  A B C)
set(short justOne)

foreach(varLong varShort IN ZIP_LISTS long short)
    message("Vars: ${varLong} ${varShort}")
endforeach()

变量：justOne
变量：B
变量：C

Vars: A justOne
Vars: B
Vars: C

foreach(loopVar RANGE start stop [step])

foreach(loopVar RANGE start stop [step])

foreach(loopVar RANGE value)

foreach(loopVar RANGE value)

while(condition)
    # ...
endwhile()

while(condition)
    # ...
endwhile()

foreach(outerVar IN ITEMS a b c)
    unset(s)

    foreach(innerVar IN ITEMS 1 2 3)
        # Stop inner loop once string s gets long
        list(APPEND s "${outerVar}${innerVar}")
        string(LENGTH "${s}" length)
        if(length GREATER 5)
            break()       ①
        endif()

        # Do no more processing if outerVar is "b"
        if(outerVar STREQUAL "b")
            continue()    ②
        endif()

        message("Processing ${outerVar}-${innerVar}")
    endforeach()

    message("Accumulated list: ${s}")
endforeach()

foreach(outerVar IN ITEMS a b c)
    unset(s)

    foreach(innerVar IN ITEMS 1 2 3)
        # Stop inner loop once string s gets long
        list(APPEND s "${outerVar}${innerVar}")
        string(LENGTH "${s}" length)
        if(length GREATER 5)
            break()       ①
        endif()

        # Do no more processing if outerVar is "b"
        if(outerVar STREQUAL "b")
            continue()    ②
        endif()

        message("Processing ${outerVar}-${innerVar}")
    endforeach()

    message("Accumulated list: ${s}")
endforeach()

处理a-1
处理a-2
累计列表：a1;a2;a3
累计列表：b1;b2;b3
处理c-1
处理c-2
累计列表：c1;c2;c3

Processing a-1
Processing a-2
Accumulated list: a1;a2;a3
Accumulated list: b1;b2;b3
Processing c-1
Processing c-2
Accumulated list: c1;c2;c3

6.3. 推荐做法

6.3. Recommended Practices

最大限度地减少字符串被无意解释为if(),foreach()和while()命令中的变量的机会。避免带引号的一元表达式，更喜欢使用字符串比较操作。强烈建议将最低 CMake 版本设置为至少 3.1，以禁用允许将带引号的字符串值隐式转换为变量名称的旧行为。

Minimize opportunities for strings to be unintentionally interpreted as variables in if(), foreach() and while() commands. Avoid unary expressions with quotes, prefer to use a string comparison operation instead. Strongly prefer to set a minimum CMake version of at least 3.1 to disable the old behavior that allowed implicit conversion of quoted string values to variable names.

当需要在命令和组捕获变量中进行正则表达式匹配时if(xxx MATCHES regex)，通常建议 CMAKE_MATCH_<n>尽快将匹配结果存储在普通变量中。这些变量将被执行任何类型的正则表达式操作的下一个命令覆盖。

When regular expression matching in if(xxx MATCHES regex) commands and the group capture variables are needed, it is generally advisable to store the CMAKE_MATCH_<n> match results in ordinary variables as soon as possible. These variables will be overwritten by the next command that does any sort of regular expression operation.

更喜欢使用循环命令，以避免出现歧义或误导性的代码。如果使用 的 RANGE 形式foreach()，请始终指定起始值和结束值。如果迭代项目，请考虑使用IN LISTS或 IN ITEMS表单是否比裸foreach(loopVar item1 item2 …​)表单更清楚地传达正在执行的操作。

Prefer to use looping commands which avoid ambiguous or misleading code. If using the RANGE form of foreach(), always specify both the start and end values. If iterating over items, consider whether using the IN LISTS or IN ITEMS forms communicate more clearly what is being done rather than a bare foreach(loopVar item1 item2 …​) form.

7.1. 添加子目录()

7.1. add_subdirectory()

该add_subdirectory()命令允许项目将另一个目录带入构建中。该目录必须有自己的CMakeLists.txt文件，该文件将在调用时进行处理add_subdirectory()，并在项目的构建树中为其创建相应的目录。

The add_subdirectory() command allows a project to bring another directory into the build. That directory must have its own CMakeLists.txt file which will be processed at the point where add_subdirectory() is called and a corresponding directory will be created for it in the project’s build tree.

add_subdirectory(sourceDir [binaryDir] [EXCLUDE_FROM_ALL])

add_subdirectory(sourceDir [binaryDir] [EXCLUDE_FROM_ALL])

尽管通常是，但不一定sourceDir是源树中的子目录。可以添加任何目录，sourceDir指定为绝对路径或相对路径，后者相对于当前源目录。通常仅在添加主源树外部的目录时才需要绝对路径。

The sourceDir does not have to be a subdirectory within the source tree, although it usually is. Any directory can be added, with sourceDir being specified as either an absolute or relative path, the latter being relative to the current source directory. Absolute paths are typically only needed when adding directories that are outside the main source tree.

通常binaryDir不需要指定。省略时，CMake 在构建树中创建一个与sourceDir. 如果 sourceDir包含任何路径组件，这些组件将镜像到 binaryDirCMake 创建的路径中。或者，binaryDir可以显式指定为绝对路径或相对路径，后者相对于当前二进制目录进行评估（稍后将更详细地讨论）。如果sourceDir是源树外部的路径，则 CMake 需要 binaryDir指定 ，因为无法再自动构造相应的相对路径。

Normally, the binaryDir does not need to be specified. When omitted, CMake creates a directory in the build tree with the same name as the sourceDir. If sourceDir contains any path components, these will be mirrored in the binaryDir created by CMake. Alternatively, the binaryDir can be explicitly specified as either an absolute or relative path, with the latter being evaluated relative to the current binary directory (discussed in more detail shortly). If sourceDir is a path outside the source tree, CMake requires the binaryDir to be specified since a corresponding relative path can no longer be constructed automatically.

可选关键字旨在控制正在添加的子目录中定义的目标是否应默认EXCLUDE_FROM_ALL包含在项目的 目标中。ALL不幸的是，对于某些 CMake 版本和项目生成器，它并不总是按预期运行，甚至可能导致构建损坏。

The optional EXCLUDE_FROM_ALL keyword is intended to control whether targets defined in the subdirectory being added should be included in the project’s ALL target by default. Unfortunately, for some CMake versions and project generators, it doesn’t always act as expected and can even result in broken builds.

cmake_minimum_required(VERSION 3.0)
project(MyApp)

message("top:   CMAKE_SOURCE_DIR         = ${CMAKE_SOURCE_DIR}")
message("top:   CMAKE_BINARY_DIR         = ${CMAKE_BINARY_DIR}")
message("top:   CMAKE_CURRENT_SOURCE_DIR = ${CMAKE_CURRENT_SOURCE_DIR}")
message("top:   CMAKE_CURRENT_BINARY_DIR = ${CMAKE_CURRENT_BINARY_DIR}")

add_subdirectory(mysub)

message("top:   CMAKE_CURRENT_SOURCE_DIR = ${CMAKE_CURRENT_SOURCE_DIR}")
message("top:   CMAKE_CURRENT_BINARY_DIR = ${CMAKE_CURRENT_BINARY_DIR}")

cmake_minimum_required(VERSION 3.0)
project(MyApp)

message("top:   CMAKE_SOURCE_DIR         = ${CMAKE_SOURCE_DIR}")
message("top:   CMAKE_BINARY_DIR         = ${CMAKE_BINARY_DIR}")
message("top:   CMAKE_CURRENT_SOURCE_DIR = ${CMAKE_CURRENT_SOURCE_DIR}")
message("top:   CMAKE_CURRENT_BINARY_DIR = ${CMAKE_CURRENT_BINARY_DIR}")

add_subdirectory(mysub)

message("top:   CMAKE_CURRENT_SOURCE_DIR = ${CMAKE_CURRENT_SOURCE_DIR}")
message("top:   CMAKE_CURRENT_BINARY_DIR = ${CMAKE_CURRENT_BINARY_DIR}")

message("mysub: CMAKE_SOURCE_DIR         = ${CMAKE_SOURCE_DIR}")
message("mysub: CMAKE_BINARY_DIR         = ${CMAKE_BINARY_DIR}")
message("mysub: CMAKE_CURRENT_SOURCE_DIR = ${CMAKE_CURRENT_SOURCE_DIR}")
message("mysub: CMAKE_CURRENT_BINARY_DIR = ${CMAKE_CURRENT_BINARY_DIR}")

message("mysub: CMAKE_SOURCE_DIR         = ${CMAKE_SOURCE_DIR}")
message("mysub: CMAKE_BINARY_DIR         = ${CMAKE_BINARY_DIR}")
message("mysub: CMAKE_CURRENT_SOURCE_DIR = ${CMAKE_CURRENT_SOURCE_DIR}")
message("mysub: CMAKE_CURRENT_BINARY_DIR = ${CMAKE_CURRENT_BINARY_DIR}")

顶部：CMAKE_SOURCE_DIR = /某处/src
顶部：CMAKE_BINARY_DIR = /某处/构建
顶部：CMAKE_CURRENT_SOURCE_DIR = /某处/src
顶部：CMAKE_CURRENT_BINARY_DIR = /某处/构建
mysub：CMAKE_SOURCE_DIR = /某处/src
mysub：CMAKE_BINARY_DIR = /某处/构建
mysub: CMAKE_CURRENT_SOURCE_DIR = /somewhere/src/mysub
mysub: CMAKE_CURRENT_BINARY_DIR = /somewhere/build/mysub
顶部：CMAKE_CURRENT_SOURCE_DIR = /某处/src
顶部：CMAKE_CURRENT_BINARY_DIR = /某处/构建

top:   CMAKE_SOURCE_DIR         = /somewhere/src
top:   CMAKE_BINARY_DIR         = /somewhere/build
top:   CMAKE_CURRENT_SOURCE_DIR = /somewhere/src
top:   CMAKE_CURRENT_BINARY_DIR = /somewhere/build
mysub: CMAKE_SOURCE_DIR         = /somewhere/src
mysub: CMAKE_BINARY_DIR         = /somewhere/build
mysub: CMAKE_CURRENT_SOURCE_DIR = /somewhere/src/mysub
mysub: CMAKE_CURRENT_BINARY_DIR = /somewhere/build/mysub
top:   CMAKE_CURRENT_SOURCE_DIR = /somewhere/src
top:   CMAKE_CURRENT_BINARY_DIR = /somewhere/build

set(myVar foo)
message("Parent (before): myVar    = ${myVar}")
message("Parent (before): childVar = ${childVar}")

add_subdirectory(subdir)

message("Parent (after):  myVar    = ${myVar}")
message("Parent (after):  childVar = ${childVar}")

set(myVar foo)
message("Parent (before): myVar    = ${myVar}")
message("Parent (before): childVar = ${childVar}")

add_subdirectory(subdir)

message("Parent (after):  myVar    = ${myVar}")
message("Parent (after):  childVar = ${childVar}")

message("Child  (before): myVar    = ${myVar}")
message("Child  (before): childVar = ${childVar}")

set(myVar bar)
set(childVar fuzz)

message("Child  (after):  myVar    = ${myVar}")
message("Child  (after):  childVar = ${childVar}")

message("Child  (before): myVar    = ${myVar}")
message("Child  (before): childVar = ${childVar}")

set(myVar bar)
set(childVar fuzz)

message("Child  (after):  myVar    = ${myVar}")
message("Child  (after):  childVar = ${childVar}")

父级（之前）：myVar = foo      ①
父级（之前）：childVar =          ②
子级（之前）：myVar = foo      ③
子级（之前）：childVar =          ④
子级（之后）：myVar = bar      ⑤
子级（之后）：childVar = fuzz     ⑥
父级（之后）：myVar = foo      ⑦
父级（之后）：childVar =          ⑧

Parent (before): myVar    = foo     ①
Parent (before): childVar =         ②
Child  (before): myVar    = foo     ③
Child  (before): childVar =         ④
Child  (after):  myVar    = bar     ⑤
Child  (after):  childVar = fuzz    ⑥
Parent (after):  myVar    = foo     ⑦
Parent (after):  childVar =         ⑧

set(myVar foo)
message("Parent (before): myVar = ${myVar}")
add_subdirectory(subdir)
message("Parent (after):  myVar = ${myVar}")

set(myVar foo)
message("Parent (before): myVar = ${myVar}")
add_subdirectory(subdir)
message("Parent (after):  myVar = ${myVar}")

message("Child  (before): myVar = ${myVar}")
set(myVar bar PARENT_SCOPE)
message("Child  (after):  myVar = ${myVar}")

message("Child  (before): myVar = ${myVar}")
set(myVar bar PARENT_SCOPE)
message("Child  (after):  myVar = ${myVar}")

父级（之前）：myVar = foo
子级（之前）：myVar = foo
子级（之后）：myVar = foo     ①
父级（之后）：myVar = bar     ②

Parent (before): myVar = foo
Child  (before): myVar = foo
Child  (after):  myVar = foo    ①
Parent (after):  myVar = bar    ②

set(localVar bar)
set(myVar ${localVar} PARENT_SCOPE)

set(localVar bar)
set(myVar ${localVar} PARENT_SCOPE)

7.2. 包括（）

7.2. include()

CMake 提供的从其他目录拉取内容的另一种方法是命令include()，它有以下两种形式：

The other method CMake provides for pulling in content from other directories is the include() command, which has the following two forms:

include(fileName
    [OPTIONAL] [RESULT_VARIABLE myVar] [NO_POLICY_SCOPE]
)
include(module
    [OPTIONAL] [RESULT_VARIABLE myVar] [NO_POLICY_SCOPE]
)

include(fileName
    [OPTIONAL] [RESULT_VARIABLE myVar] [NO_POLICY_SCOPE]
)
include(module
    [OPTIONAL] [RESULT_VARIABLE myVar] [NO_POLICY_SCOPE]
)

第一种形式有点类似于add_subdirectory()，但有重要的区别：

The first form is somewhat analogous to add_subdirectory(), but there are important differences:

该include()命令的第二种形式具有完全不同的目的。它用于加载命名模块，这是第 11 章模块中深入讨论的主题 。除第一点外，上述所有要点也适用于第二种形式。

The second form of the include() command serves an entirely different purpose. It is used to load the named module, a topic covered in depth in Chapter 11, Modules. All but the first of the above points also hold true for this second form.

由于 的值在被调用CMAKE_CURRENT_SOURCE_DIR时不会改变include() ，因此包含的文件似乎很难计算出它所在的目录。CMAKE_CURRENT_SOURCE_DIR将包含调用文件的位置include()，而不是包含包含文件的目录。此外，与始终为 的add_subdirectory()情况不同，使用 时文件的名称可以是任何名称，因此包含的文件可能很难确定其自己的名称。为了解决此类情况，CMake 提供了一组附加变量：fileNameCMakeLists.txtinclude()

Since the value of CMAKE_CURRENT_SOURCE_DIR does not change when include() is called, it may seem difficult for the included file to work out the directory in which it resides. CMAKE_CURRENT_SOURCE_DIR will contain the location of the file from where include() was called, not the directory containing the included file. Furthermore, unlike add_subdirectory() where the fileName will always be CMakeLists.txt, the name of the file can be anything when using include(), so it can be difficult for the included file to determine its own name. To address situations like these, CMake provides an additional set of variables:

值得注意的是，上述三个变量适用于CMake 处理的任何include()文件，而不仅仅是那些由命令拉入的文件。CMakeLists.txt即使对于通过 拉入的文件，它们也具有与上述相同的值add_subdirectory()，在这种情况下，CMAKE_CURRENT_LIST_DIR 它们将具有与 相同的值CMAKE_CURRENT_SOURCE_DIR。以下示例演示了该行为：

It is important to note that the above three variables work for any file being processed by CMake, not just those pulled in by an include() command. They have the same values as described above even for a CMakeLists.txt file pulled in via add_subdirectory(), in which case CMAKE_CURRENT_LIST_DIR would have the same value as CMAKE_CURRENT_SOURCE_DIR. The following example demonstrates the behavior:

add_subdirectory(subdir)
message("")
include(subdir/CMakeLists.txt)

add_subdirectory(subdir)
message("")
include(subdir/CMakeLists.txt)

message("CMAKE_CURRENT_SOURCE_DIR = ${CMAKE_CURRENT_SOURCE_DIR}")
message("CMAKE_CURRENT_BINARY_DIR = ${CMAKE_CURRENT_BINARY_DIR}")
message("CMAKE_CURRENT_LIST_DIR   = ${CMAKE_CURRENT_LIST_DIR}")
message("CMAKE_CURRENT_LIST_FILE  = ${CMAKE_CURRENT_LIST_FILE}")
message("CMAKE_CURRENT_LIST_LINE  = ${CMAKE_CURRENT_LIST_LINE}")

message("CMAKE_CURRENT_SOURCE_DIR = ${CMAKE_CURRENT_SOURCE_DIR}")
message("CMAKE_CURRENT_BINARY_DIR = ${CMAKE_CURRENT_BINARY_DIR}")
message("CMAKE_CURRENT_LIST_DIR   = ${CMAKE_CURRENT_LIST_DIR}")
message("CMAKE_CURRENT_LIST_FILE  = ${CMAKE_CURRENT_LIST_FILE}")
message("CMAKE_CURRENT_LIST_LINE  = ${CMAKE_CURRENT_LIST_LINE}")

这会产生如下输出：

This produces output like the following:

CMAKE_CURRENT_SOURCE_DIR = /某处/src/subdir
CMAKE_CURRENT_BINARY_DIR = /某处/构建/子目录
CMAKE_CURRENT_LIST_DIR = /某处/src/subdir
CMAKE_CURRENT_LIST_FILE = /somewhere/src/subdir/CMakeLists.txt
CMAKE_CURRENT_LIST_LINE = 5

CMAKE_CURRENT_SOURCE_DIR = /某处/src
CMAKE_CURRENT_BINARY_DIR = /某处/构建
CMAKE_CURRENT_LIST_DIR = /某处/src/subdir
CMAKE_CURRENT_LIST_FILE = /somewhere/src/subdir/CMakeLists.txt
CMAKE_CURRENT_LIST_LINE = 5

CMAKE_CURRENT_SOURCE_DIR = /somewhere/src/subdir
CMAKE_CURRENT_BINARY_DIR = /somewhere/build/subdir
CMAKE_CURRENT_LIST_DIR   = /somewhere/src/subdir
CMAKE_CURRENT_LIST_FILE  = /somewhere/src/subdir/CMakeLists.txt
CMAKE_CURRENT_LIST_LINE  = 5

CMAKE_CURRENT_SOURCE_DIR = /somewhere/src
CMAKE_CURRENT_BINARY_DIR = /somewhere/build
CMAKE_CURRENT_LIST_DIR   = /somewhere/src/subdir
CMAKE_CURRENT_LIST_FILE  = /somewhere/src/subdir/CMakeLists.txt
CMAKE_CURRENT_LIST_LINE  = 5

上面的示例还突出了该 include()命令的另一个有趣的特征。它可用于包含先前已包含在构建中的文件中的内容。如果大型、复杂项目的不同子目录都希望在项目公共区域的某个文件中使用 CMake 代码，则它们可以include()独立地使用该文件。

The above example also highlights another interesting characteristic of the include() command. It can be used to include content from a file which has already been included in the build previously. If different subdirectories of a large, complex project both want to make use of CMake code in some file in a common area of the project, they may both include() that file independently.

7.3. 项目相关变量

7.3. Project-relative Variables

正如将在后面的章节中看到的，有多种场景需要构建相对于源目录或构建目录中的位置的路径。考虑一个这样的示例，其中项目需要构建驻留在其顶级源目录中的文件的路径。从第 7.1.1 节“源和二进制目录变量”来看，CMAKE_SOURCE_DIR似乎很自然，允许${CMAKE_SOURCE_DIR}/someFile使用类似的路径。但请考虑一下，如果该项目后来通过将其引入父构建而合并到另一个父项目中，会发生什么情况add_subdirectory()。它可以用作 git 子模块，也可以使用第 28 章“外部内容”和第 29 章“项目组织”中讨论的技术之一按需获取。原来项目源代码树的顶部现在是父项目源代码树中的子目录。 CMAKE_SOURCE_DIR现在指向父项目的顶部，因此文件路径将指向错误的目录。也存在类似的陷阱CMAKE_BINARY_DIR。

As will be seen in later chapters, there are various scenarios where paths relative to a location in the source or build directory need to be constructed. Consider one such example where a project needs to construct a path to a file that resides in its top level source directory. From Section 7.1.1, “Source And Binary Directory Variables”, CMAKE_SOURCE_DIR seems to be a natural fit, allowing a path like ${CMAKE_SOURCE_DIR}/someFile to be used. But consider what happens if that project is later incorporated into another parent project by bringing it into the parent build via add_subdirectory(). It could be used as a git submodule or fetched on demand using one of the techniques discussed in Chapter 28, External Content and Chapter 29, Project Organization. What used to be the top of the original project’s source tree is now a subdirectory within the parent project’s source tree. CMAKE_SOURCE_DIR now points to the top of the parent project, so the file path will be pointing to the wrong directory. A similar trap exists for CMAKE_BINARY_DIR.

上述场景在在线教程和较旧的项目中经常遇到，但很容易避免。该project()命令设置一些变量，这些变量提供了一种更可靠的方法来定义相对于目录层次结构中的位置的路径。project()以下变量在至少被调用一次后才可用：

The above scenario is encountered surprisingly often in online tutorials and older projects, but it can be easily avoided. The project() command sets some variables that provide a much more robust way of defining paths relative to locations in the directory hierarchy. The following variables will be available after project() has been called at least once:

以下示例演示了如何使用这些变量（这些 …​_BINARY_DIR变量遵循与所示变量类似的模式…​_SOURCE_DIR ）。

The following example demonstrates how these variables can be used (the …​_BINARY_DIR variables follow a similar pattern to the …​_SOURCE_DIR variables shown).

cmake_minimum_required(VERSION 3.0)
project(topLevel)

message("Top level:")
message("  PROJECT_SOURCE_DIR  = ${PROJECT_SOURCE_DIR}")
message("  topLevel_SOURCE_DIR = ${topLevel_SOURCE_DIR}")

add_subdirectory(child)

cmake_minimum_required(VERSION 3.0)
project(topLevel)

message("Top level:")
message("  PROJECT_SOURCE_DIR  = ${PROJECT_SOURCE_DIR}")
message("  topLevel_SOURCE_DIR = ${topLevel_SOURCE_DIR}")

add_subdirectory(child)

message("Child:")
message("  PROJECT_SOURCE_DIR (before) = ${PROJECT_SOURCE_DIR}")

project(child)

message("  PROJECT_SOURCE_DIR (after)  = ${PROJECT_SOURCE_DIR}")
message("  child_SOURCE_DIR            = ${child_SOURCE_DIR}")

add_subdirectory(grandchild)

message("Child:")
message("  PROJECT_SOURCE_DIR (before) = ${PROJECT_SOURCE_DIR}")

project(child)

message("  PROJECT_SOURCE_DIR (after)  = ${PROJECT_SOURCE_DIR}")
message("  child_SOURCE_DIR            = ${child_SOURCE_DIR}")

add_subdirectory(grandchild)

message("Grandchild:")
message("  PROJECT_SOURCE_DIR  = ${PROJECT_SOURCE_DIR}")
message("  child_SOURCE_DIR    = ${child_SOURCE_DIR}")
message("  topLevel_SOURCE_DIR = ${topLevel_SOURCE_DIR}")

message("Grandchild:")
message("  PROJECT_SOURCE_DIR  = ${PROJECT_SOURCE_DIR}")
message("  child_SOURCE_DIR    = ${child_SOURCE_DIR}")
message("  topLevel_SOURCE_DIR = ${topLevel_SOURCE_DIR}")

cmake在此项目层次结构的顶层运行将提供类似于以下内容的输出：

Running cmake on the top level of this project hierarchy would give output similar to the following:

顶层：
  PROJECT_SOURCE_DIR = /某处/src
  topLevel_SOURCE_DIR = /某处/src
孩子：
  PROJECT_SOURCE_DIR（之前）= /somewhere/src
  PROJECT_SOURCE_DIR（之后）= /somewhere/src/child
  child_SOURCE_DIR = /某处/src/child
孙子：
  PROJECT_SOURCE_DIR = /某处/src/child
  child_SOURCE_DIR = /某处/src/child
  topLevel_SOURCE_DIR = /某处/src

Top level:
  PROJECT_SOURCE_DIR  = /somewhere/src
  topLevel_SOURCE_DIR = /somewhere/src
Child:
  PROJECT_SOURCE_DIR (before) = /somewhere/src
  PROJECT_SOURCE_DIR (after)  = /somewhere/src/child
  child_SOURCE_DIR            = /somewhere/src/child
Grandchild:
  PROJECT_SOURCE_DIR  = /somewhere/src/child
  child_SOURCE_DIR    = /somewhere/src/child
  topLevel_SOURCE_DIR = /somewhere/src

上面的例子显示了项目相关变量的多功能性。可以从目录层次结构的任何部分使用它们来可靠地引用项目中的任何其他目录。对于本节开头讨论的场景，使用 ${PROJECT_SOURCE_DIR}/someFile或${projectName_SOURCE_DIR}/someFile 代替${CMAKE_SOURCE_DIR}/someFile将确保路径 someFile正确，无论项目是独立构建还是合并到更大的项目层次结构中。

The above example shows the versatility of the project-related variables. They can be used from any part of the directory hierarchy to robustly refer to any other directory in the project. For the scenario discussed at the start of this section, using ${PROJECT_SOURCE_DIR}/someFile or perhaps ${projectName_SOURCE_DIR}/someFile instead of ${CMAKE_SOURCE_DIR}/someFile would ensure that the path to someFile would be correct, regardless of whether the project is being built stand-alone or being incorporated into a larger project hierarchy.

一些分层构建安排允许项目独立构建或作为较大父项目的一部分构建（请参见第 28.2 节“FetchContent”）。项目的某些部分可能只有在构建的顶部才有意义，例如设置打包支持。CMAKE_SOURCE_DIR项目可以通过比较和的值来检测是否是顶级 CMAKE_CURRENT_SOURCE_DIR。如果它们相同，则当前目录范围必须是源代码树的顶层。

Some hierarchical build arrangements allow a project to be built either stand-alone or as part of a larger parent project (see Section 28.2, “FetchContent”). Some parts of the project might only make sense if it is the top of the build, such as setting up packaging support. A project can detect whether it is the top level by comparing the value of CMAKE_SOURCE_DIR with CMAKE_CURRENT_SOURCE_DIR. If they are the same, then the current directory scope must be the top level of the source tree.

if(CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR)
    add_subdirectory(packaging)
endif()

if(CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR)
    add_subdirectory(packaging)
endif()

所有版本的 CMake 都支持上述技术，并且是一种非常常见的模式。在 CMake 3.21 或更高版本中，PROJECT_IS_TOP_LEVEL提供了一个专用变量，它可以实现相同的结果，但其意图更清晰：

The above technique is supported by all versions of CMake and is a very common pattern. With CMake 3.21 or later, a dedicated PROJECT_IS_TOP_LEVEL variable is provided which can achieve the same result, but is clearer in its intent:

# Requires CMake 3.21 or later
if(PROJECT_IS_TOP_LEVEL)
    add_subdirectory(packaging)
endif()

# Requires CMake 3.21 or later
if(PROJECT_IS_TOP_LEVEL)
    add_subdirectory(packaging)
endif()

PROJECT_IS_TOP_LEVEL如果当前目录范围或以上目录中的最新调用 project()位于顶级 文件中，则的值将为 true CMakeLists.txt。<projectName>_IS_TOP_LEVELCMake 3.21 或更高版本还为每次调用 定义了类似的变量project()。它被创建为缓存变量，因此可以从任何目录范围读取。 对应于感兴趣的命令<projectName>的名称。当当前范围和感兴趣的项目范围之间project()可能存在中间调用时，此替代变量非常有用 。project()

The value of PROJECT_IS_TOP_LEVEL will be true if the most recent call to project() in the current directory scope or above was in the top level CMakeLists.txt file. A similar variable, <projectName>_IS_TOP_LEVEL, is also defined by CMake 3.21 or later for every call to project(). It is created as a cache variable, so it can be read from any directory scope. <projectName> corresponds to the name given to the project() command of interest. This alternative variable is useful when there may be intervening calls to project() between the current scope and the scope of the project of interest.

7.4. 提前结束处理

7.4. Ending Processing Early

有时，项目可能希望停止处理当前文件的其余部分并将控制权返回给调用者。该 return()命令正好可以用于此目的，但请注意它不能将值返回给调用者。它的唯一作用是结束当前作用域的处理。如果不是从函数内部调用，return()则结束当前文件的处理，无论它是通过 include()或引入的add_subdirectory()。第 8.4 节“范围”return()介绍了函数内部调用的影响，包括对可能导致无意中从当前文件返回的常见错误的特别注意。

There can be occasions where a project may want to stop processing the remainder of the current file and return control back to the caller. The return() command can be used for exactly this purpose, but note that it cannot return a value to the caller. Its only effect is to end processing of the current scope. If not called from inside a function, return() ends processing of the current file regardless of whether it was brought in via include() or add_subdirectory(). The effect of calling return() inside a function is covered in Section 8.4, “Scope”, including special attention for a common mistake that can result in returning from the current file unintentionally.

如上一节所述，项目的不同部分可能包含来自多个位置的相同文件。有时可能需要检查这一点并仅包含该文件一次，并提前返回以进行后续包含，以防止多次重新处理该文件。这与 C/C++ 标头的情况非常相似，并且使用类似形式的包含防护是相当常见的：

As noted in the previous section, different parts of a project may include the same file from multiple places. It can sometimes be desirable to check for this and only include the file once, returning early for subsequent inclusions to prevent reprocessing the file multiple times. This is very similar to the situation for C/C++ headers and it is fairly common to see a similar form of include guard used:

if(DEFINED cool_stuff_include_guard)
    return()
endif()

set(cool_stuff_include_guard 1)
# ...

if(DEFINED cool_stuff_include_guard)
    return()
endif()

set(cool_stuff_include_guard 1)
# ...

使用 CMake 3.10 或更高版本，可以使用专用命令更简洁、更稳健地表达这一点，其行为类似于#pragma onceC/C++ 的：

With CMake 3.10 or later, this can be expressed more succinctly and robustly with a dedicated command whose behavior is analogous to the #pragma once of C/C++:

include_guard()

include_guard()

与手动编写if-endif代码相比，这更加健壮，因为它在内部处理保护变量的名称。该命令还接受可选的关键字参数DIRECTORY或GLOBAL指定不同的范围来检查先前已处理的文件，但在大多数情况下不太可能需要这些关键字。如果没有指定任何参数，则假定变量作用域，并且效果与上面的代码完全相同if-endif。GLOBAL确保命令结束文件的处理（如果该文件在项目中的其他任何地方之前已被处理过）（即变量范围被忽略）。DIRECTORY仅检查当前目录范围内及以下目录范围内的先前处理。

Compared to manually writing out the if-endif code, this is more robust because it handles the name of the guard variable internally. The command also accepts an optional keyword argument DIRECTORY or GLOBAL to specify a different scope within which to check for the file having been processed previously, but these keywords are unlikely to be needed in most situations. With neither argument specified, variable scope is assumed and the effect is exactly equivalent to the if-endif code above. GLOBAL ensures the command ends processing of the file if it has been processed before anywhere else in the project (i.e. variable scope is ignored). DIRECTORY checks for previous processing only within the current directory scope and below.

7.5。推荐做法

7.5. Recommended Practices

add_subdirectory()使用或include()将另一个目录引入构建之间的最佳选择并不总是显而易见的。一方面， add_subdirectory()更简单并且可以更好地保持目录相对独立，因为它创建了自己的范围。另一方面，某些 CMake 命令具有限制，仅允许它们对当前文件范围内定义的内容进行操作，因此include()在这些情况下效果更好。第 29.5.1 节“目标源”讨论了本主题的一些方面。

The best choice between using add_subdirectory() or include() to bring another directory into the build is not always obvious. On the one hand, add_subdirectory() is simpler and does a better job of keeping directories relatively self contained because it creates its own scope. On the other, some CMake commands have restrictions which only allow them to operate on things defined within the current file scope, so include() works better for those cases. Section 29.5.1, “Target Sources” discusses some aspects of this topic.

作为一般指南，大多数简单的项目可能最好选择add_subdirectory()使用include(). 它促进了项目的更清晰的定义，并允许CMakeLists.txt 给定目录更多地关注该目录需要定义的内容。遵循这一策略将促进整个项目中信息的更好本地化，并且也倾向于仅在需要和带来有用好处的地方引入复杂性。这并不是说它include()本身比 更复杂 add_subdirectory()，而是使用include()往往会导致需要更明确地拼写文件路径，因为 CMake 认为当前源目录不是包含文件的目录。在最近的 CMake 版本中，与从不同目录调用某些命令相关的许多限制也已被删除，这进一步强化了偏好的论点add_subdirectory()。

As a general guide, most simple projects are probably better off preferring to use add_subdirectory() over include(). It promotes cleaner definition of the project and allows the CMakeLists.txt for a given directory to focus more on just what that directory needs to define. Following this strategy will promote better locality of information throughout the project and will also tend to introduce complexity only where it is needed and where it brings useful benefits. It’s not that include() itself is any more complicated than add_subdirectory(), but the use of include() tends to result in paths to files needing to be more explicitly spelled out, since what CMake considers the current source directory is not that of the included file. Many of the restrictions associated with calling certain commands from different directories have been removed in more recent CMake versions too, which further strengthens the argument to prefer add_subdirectory().

无论是否使用add_subdirectory()或include()两者的组合，该CMAKE_CURRENT_LIST_DIR变量通常都是比 更好的选择CMAKE_CURRENT_SOURCE_DIR。通过养成尽早使用的习惯，随着项目复杂性的增加，在和CMAKE_CURRENT_LIST_DIR之间进行切换以及移动整个目录来重组项目会变得更加容易。add_subdirectory()include()

Irrespective of whether using add_subdirectory(), include() or a combination of both, the CMAKE_CURRENT_LIST_DIR variable is generally going to be a better choice than CMAKE_CURRENT_SOURCE_DIR. By establishing the habit of using CMAKE_CURRENT_LIST_DIR early, it is much easier to switch between add_subdirectory() and include() as a project grows in complexity and to move entire directories to restructure a project.

如果可能，请避免使用CMAKE_SOURCE_DIR和CMAKE_BINARY_DIR 变量，因为这些通常会破坏项目合并到更大项目层次结构中的能力。在绝大多数情况下，PROJECT_SOURCE_DIR和PROJECT_BINARY_DIR，或它们特定于项目的等效项projectName_SOURCE_DIR和 projectName_BINARY_DIR是更合适使用的变量。

Where possible, avoid using the CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR variables, as these typically break the ability of the project to be incorporated into a larger project hierarchy. In the vast majority of cases, PROJECT_SOURCE_DIR and PROJECT_BINARY_DIR, or their project-specific equivalents projectName_SOURCE_DIR and projectName_BINARY_DIR are more appropriate variables to use.

如果项目需要 CMake 3.10 或更高版本，则 在必须防止多次包含文件的情况下，最好使用include_guard()不带参数的命令，而不是显式块。if-endif

If the project requires CMake 3.10 or later, prefer to use the include_guard() command without arguments instead of an explicit if-endif block in cases where multiple inclusion of a file must be prevented.

project()避免任意调用每个子目录的做法CMakeLists.txt 。仅 当子目录可以被视为或多或少独立的项目时，才考虑将project()命令放入子目录的文件中。CMakeLists.txt除非整个构建具有非常多的目标，否则几乎不需要调用project()顶级CMakeLists.txt文件之外的任何地方。

Avoid the practice of arbitrarily calling project() in the CMakeLists.txt of every subdirectory. Only consider putting a project() command in a subdirectory’s CMakeLists.txt file if that subdirectory can be treated as a more or less standalone project. Unless the whole build has a very high number of targets, there is little need to call project() anywhere other than in the top level CMakeLists.txt file.

8.1. 基础

8.1. The Basics

CMake 中的函数和宏与 C/C++ 中的同名函数和宏具有非常相似的特征。函数引入了新的作用域，函数参数成为函数体内可访问的变量。另一方面，宏有效地将其主体粘贴到调用点，并且宏参数被替换为简单的字符串替换。这些行为反映了函数和宏在 C/C++ 中的工作方式#define。CMake 函数或宏定义如下：

Functions and macros in CMake have very similar characteristics to their same-named counterparts in C/C++. Functions introduce a new scope and the function arguments become variables accessible inside the function body. Macros, on the other hand, effectively paste their body into the point of the call and the macro arguments are substituted as simple string replacements. These behaviors mirror the way functions and #define macros work in C/C++. A CMake function or macro is defined as follows:

function(name [arg1 [arg2 [...]]])
   # Function body (i.e. commands) ...
endfunction()

macro(name [arg1 [arg2 [...]]])
   # Macro body (i.e. commands) ...
endmacro()

function(name [arg1 [arg2 [...]]])
   # Function body (i.e. commands) ...
endfunction()

macro(name [arg1 [arg2 [...]]])
   # Macro body (i.e. commands) ...
endmacro()

定义后，函数或宏的调用方式与任何其他 CMake 命令完全相同。然后函数或宏的主体在调用时执行。例如：

Once defined, the function or macro is called in exactly the same way as any other CMake command. The function or macro’s body is then executed at the point of the call. For example:

function(print_me)
    message("Hello from inside a function")
    message("All done")
endfunction()

# Called like so:
print_me()

function(print_me)
    message("Hello from inside a function")
    message("All done")
endfunction()

# Called like so:
print_me()

如上所示，name参数定义了用于调用函数或宏的名称，它只能包含字母、数字和下划线。名称将不区分大小写，因此大写/小写约定更多的是风格问题（CMake 文档遵循命令名称全部小写且单词之间用下划线分隔的约定）。CMake 的早期版本要求将重复作为或name的参数 ，但新项目应该避免这种情况，因为它只会增加不必要的混乱。endfunction()endmacro()

As shown above, the name argument defines the name used to call the function or macro and it should only contain letters, numbers and underscores. The name will be treated case-insensitively, so upper/lowercase conventions are more a matter of style (the CMake documentation follows the convention that command names are all lowercase with words separated by underscores). Very early versions of CMake required the name to be repeated as an argument to endfunction() or endmacro(), but new projects should avoid this as it only adds unnecessary clutter.

8.2. 参数处理要点

8.2. Argument Handling Essentials

除了一个非常重要的区别之外，函数和宏的参数处理是相同的。对于函数，每个参数都是一个 CMake 变量，并且具有 CMake 变量的所有常见行为。例如，它们可以在if()语句中作为变量进行测试。相比之下，宏参数是字符串替换，因此用作宏调用参数的任何内容本质上都会粘贴到该参数出现在宏体中的任何位置。如果在语句中使用宏参数if()，它将被视为字符串而不是变量。以下示例及其输出演示了其中的差异：

The argument handling of functions and macros is the same except for one very important difference. For functions, each argument is a CMake variable and has all the usual behaviors of a CMake variable. For example, they can be tested in if() statements as variables. In comparison, macro arguments are string replacements, so whatever was used as the argument to the macro call is essentially pasted into wherever that argument appears in the macro body. If a macro argument is used in an if() statement, it would be treated as a string rather than a variable. The following example and its output demonstrate the difference:

function(func arg)
    if(DEFINED arg)
        message("Function arg is a defined variable")
    else()
        message("Function arg is NOT a defined variable")
    endif()
endfunction()

macro(macr arg)
    if(DEFINED arg)
        message("Macro arg is a defined variable")
    else()
        message("Macro arg is NOT a defined variable")
    endif()
endmacro()

func(foobar)
macr(foobar)

function(func arg)
    if(DEFINED arg)
        message("Function arg is a defined variable")
    else()
        message("Function arg is NOT a defined variable")
    endif()
endfunction()

macro(macr arg)
    if(DEFINED arg)
        message("Macro arg is a defined variable")
    else()
        message("Macro arg is NOT a defined variable")
    endif()
endmacro()

func(foobar)
macr(foobar)

函数arg是一个定义的变量
宏 arg 不是已定义的变量

Function arg is a defined variable
Macro arg is NOT a defined variable

除了这种差异之外，函数和宏在参数处理方面都支持相同的功能。函数定义中的每个参数都充当它所代表的参数的区分大小写的标签。对于函数，该标签的作用类似于变量，而对于宏，它的作用类似于字符串替换。即使宏参数在技术上不是变量，也可以使用通常的变量表示法在函数或宏体中访问该参数的值。

Aside from that difference, functions and macros both support the same features when it comes to argument processing. Each argument in the function definition serves as a case-sensitive label for the argument it represents. For functions, that label acts like a variable, whereas for macros it acts like a string substitution. The value of that argument can be accessed in the function or macro body using the usual variable notation, even though macro arguments are not technically variables.

function(func myArg)
    message("myArg = ${myArg}")
endfunction()

macro(macr myArg)
    message("myArg = ${myArg}")
endmacro()

func(foobar)
macr(foobar)

function(func myArg)
    message("myArg = ${myArg}")
endfunction()

macro(macr myArg)
    message("myArg = ${myArg}")
endmacro()

func(foobar)
macr(foobar)

调用func()和打印macr()相同的内容：

Both the call to func() and the call to macr() print the same thing:

myArg = foobar

myArg = foobar

除了命名参数之外，函数和宏还附带一组自动定义的变量（在宏的情况下是类似变量的名称），这些变量允许除了命名参数之外或代替命名参数处理参数：

In addition to the named arguments, functions and macros come with a set of automatically defined variables (or variable-like names in the case of macros) which allow processing of arguments in addition to or instead of the named ones:

除了上述内容之外，还可以使用以下形式的名称来引用每个单独的参数，ARGVx其中x是参数的编号（例如ARGV0、 ARGV1等）。这包括命名参数，因此第一个命名参数也可以通过 等引用。请注意，与 一起 ARGV0使用应被视为未定义行为。ARGVxx >= ARGC

In addition to the above, each individual argument can be referenced with a name of the form ARGVx where x is the number of the argument (e.g. ARGV0, ARGV1, etc.). This includes the named arguments, so the first named argument could also be referenced via ARGV0, etc. Note that it should be considered undefined behavior to use ARGVx with x >= ARGC.

使用名称的典型情况ARG…​包括支持可选参数和实现可以处理任意数量的项目的命令。考虑一个定义可执行目标的函数，将该目标链接到某个库并为其定义测试用例。在编写测试用例时经常会遇到这样的函数（第 25 章“测试”中介绍的主题）。该函数允许定义一次步骤，然后每个测试用例就变成一个简单的一行定义，而不是为每个测试用例重复这些步骤。

Typical situations where the ARG…​ names are used include supporting optional arguments and implementing a command which can take an arbitrary number of items to be processed. Consider a function that defines an executable target, links that target to some library and defines a test case for it. Such a function is frequently encountered when writing test cases (a topic covered in Chapter 25, Testing). Rather than repeating the steps for every test case, the function allows the steps to be defined once and then each test case becomes a simple one-line definition.

# Use a named argument for the target and treat all other
# (unnamed) arguments as the source files for the test case
function(add_mytest targetName)
    add_executable(${targetName} ${ARGN})

    target_link_libraries(${targetName} PRIVATE foobar)

    add_test(NAME    ${targetName}
             COMMAND ${targetName})
endfunction()

# Define some test cases using the above function
add_mytest(smallTest small.cpp)
add_mytest(bigTest   big.cpp algo.cpp net.cpp)

# Use a named argument for the target and treat all other
# (unnamed) arguments as the source files for the test case
function(add_mytest targetName)
    add_executable(${targetName} ${ARGN})

    target_link_libraries(${targetName} PRIVATE foobar)

    add_test(NAME    ${targetName}
             COMMAND ${targetName})
endfunction()

# Define some test cases using the above function
add_mytest(smallTest small.cpp)
add_mytest(bigTest   big.cpp algo.cpp net.cpp)

ARGN上面的例子特别显示了 的用处。它允许函数或宏采用不同数量的参数，但仍指定一组必须提供的命名参数。但是，需要注意一种可能导致意外行为的特定情况。因为宏将它们的参数视为字符串替换而不是变量，所以如果它们ARGN在需要变量名称的地方使用，则它将引用的变量将在调用宏的范围内，而不是在 ARGN宏自己的范围内论据。以下示例突出显示了这种情况：

The above example shows the usefulness of ARGN in particular. It allows a function or macro to take a varying number of arguments, yet still specify a set of named arguments which must be provided. There is, however, a specific case to be aware of which can result in unexpected behavior. Because macros treat their arguments as string substitutions rather than as variables, if they use ARGN in a place where a variable name is expected, the variable it will refer to will be in the scope from which the macro is called, not the ARGN from the macro’s own arguments. The following example highlights the situation:

# WARNING: This macro is misleading
macro(dangerous)
    # Which ARGN?
    foreach(arg IN LISTS ARGN)
        message("Argument: ${arg}")
    endforeach()
endmacro()

function(func)
    dangerous(1 2)
endfunction()

func(3)

# WARNING: This macro is misleading
macro(dangerous)
    # Which ARGN?
    foreach(arg IN LISTS ARGN)
        message("Argument: ${arg}")
    endforeach()
endmacro()

function(func)
    dangerous(1 2)
endfunction()

func(3)

上面的输出将是：

The output from the above would be:

参数：3

Argument: 3

使用LISTS关键字 with时foreach()，必须给出变量名，但ARGN为宏提供的不是变量名。当从另一个函数内部调用宏时，宏最终使用 该封闭函数中的ARGN 变量ARGN，而不是宏本身的变量。当将宏体的内容直接粘贴到调用它的函数中时（这实际上是 CMake 将对其执行的操作），情况就会变得清晰：

When using the LISTS keyword with foreach(), a variable name has to be given, but the ARGN provided for a macro is not a variable name. When the macro is called from inside another function, the macro ends up using the ARGN variable from that enclosing function, not the ARGN from the macro itself. The situation becomes clear when pasting the contents of the macro body directly into the function where it is called (which is effectively what CMake will do with it):

function(func)
    # Now it is clear, ARGN here will use the arguments
    # from func
    foreach(arg IN LISTS ARGN)
        message("Argument: ${arg}")
    endforeach()
endfunction()

function(func)
    # Now it is clear, ARGN here will use the arguments
    # from func
    foreach(arg IN LISTS ARGN)
        message("Argument: ${arg}")
    endforeach()
endfunction()

在这种情况下，请考虑将宏改为函数，或者如果它必须保留为宏，则避免将参数视为变量。对于上面的示例，可以将 的实现dangerous()改为 use foreach(arg IN ITEMS ${ARGN})，但请参阅 第 8.8 节“参数处理问题”以了解一些潜在的注意事项。

In such cases, consider making the macro a function instead, or if it must remain a macro then avoid treating arguments as variables. For the above example, the implementation of dangerous() could be changed to use foreach(arg IN ITEMS ${ARGN}) instead, but see Section 8.8, “Problems With Argument Handling” for some potential caveats.

8.3. 关键字参数

8.3. Keyword Arguments

上一节说明了如何ARG…​使用变量来处理一组不同的参数。该功能对于仅需要一组可变或可选参数的简单情况来说是足够的，但如果必须支持多个可选或可变参数集，则处理变得相当乏味。此外，与许多支持基于关键字的参数和灵活的参数排序的 CMake 自己的内置命令相比，上述基本参数处理相当严格。

The previous section illustrated how the ARG…​ variables can be used to handle a varying set of arguments. That functionality is sufficient for the simple case where only one set of varying or optional arguments is needed, but if multiple optional or variable sets of arguments must be supported, the processing becomes quite tedious. Furthermore, the basic argument handling described above is quite rigid compared to many of CMake’s own built-in commands which support keyword-based arguments and flexible argument ordering.

考虑以下target_link_libraries()命令：

Consider the target_link_libraries() command:

target_link_libraries(targetName
     <PRIVATE|PUBLIC|INTERFACE> item1 [item2 ...]
    [<PRIVATE|PUBLIC|INTERFACE> item3 [item4 ...]]
    ...
)

target_link_libraries(targetName
     <PRIVATE|PUBLIC|INTERFACE> item1 [item2 ...]
    [<PRIVATE|PUBLIC|INTERFACE> item3 [item4 ...]]
    ...
)

需要targetName作为第一个参数，但之后，调用者可以以任何顺序提供任意数量的PRIVATE,PUBLIC或INTERFACE部分，每个部分允许包含任意数量的项目。用户定义的函数和宏可以通过使用命令来支持类似级别的灵活性 cmake_parse_arguments()，命令有两种形式。所有 CMake 版本都支持第一种形式，并且适用于函数和宏：

The targetName is required as the first argument, but after that, callers can provide any number of PRIVATE, PUBLIC or INTERFACE sections in any order, with each section permitted to contain any number of items. User-defined functions and macros can support a similar level of flexibility by using the cmake_parse_arguments() command, of which there are two forms. The first form is supported by all CMake versions and works for both functions and macros:

# Needed only for CMake 3.4 and earlier
include(CMakeParseArguments)

cmake_parse_arguments(
   prefix
   valuelessKeywords singleValueKeywords multiValueKeywords
   argsToParse...
)

# Needed only for CMake 3.4 and earlier
include(CMakeParseArguments)

cmake_parse_arguments(
   prefix
   valuelessKeywords singleValueKeywords multiValueKeywords
   argsToParse...
)

该cmake_parse_arguments()命令以前由模块提供 CMakeParseArguments，但在 CMake 3.5 中成为内置命令。该include(CMakeParseArguments)行在 CMake 3.5 及更高版本中不会执行任何操作，而对于早期版本的 CMake，它将定义命令 cmake_parse_arguments()（有关 的此类用法的更多信息，请参阅第 11 章，模块include()）。

The cmake_parse_arguments() command used to be provided by the CMakeParseArguments module, but it became a built-in command in CMake 3.5. The include(CMakeParseArguments) line will do nothing in CMake 3.5 and later, while for earlier versions of CMake it will define the cmake_parse_arguments() command (see Chapter 11, Modules for more on this sort of usage of include()).

第二种形式是在 CMake 3.7 中引入的，只能在函数中使用，不能在宏中使用：

The second form was introduced in CMake 3.7 and can only be used in functions, not macros:

# Available with CMake 3.7 or later, do not use in macros
cmake_parse_arguments(
   PARSE_ARGV startIndex
   prefix
   valuelessKeywords singleValueKeywords multiValueKeywords
)

# Available with CMake 3.7 or later, do not use in macros
cmake_parse_arguments(
   PARSE_ARGV startIndex
   prefix
   valuelessKeywords singleValueKeywords multiValueKeywords
)

该命令的两种形式都很相似，唯一的区别在于它们接受要解析的参数集的方式。对于第一种形式，argsToParse通常${ARGN}不带引号。这提供了除了命名参数之外赋予封闭函数或宏的所有参数，除了一些在大多数情况下不适用的特定极端情况（请参见第 8.8 节“参数处理问题”）。

Both forms of the command are similar, differing only in the way they take in the set of arguments to parse. With the first form, argsToParse will typically be given as ${ARGN} without quotes. This provides all arguments given to the enclosing function or macro beyond the named arguments, except for a few specific corner cases that don’t apply in most situations (see Section 8.8, “Problems With Argument Handling”).

在第二种形式中，该PARSE_ARGV选项指示cmake_parse_arguments()直接从变量集中读取参数${ARGVx}，x 范围从startIndex到(ARGC - 1)。因为它直接读取变量，所以不支持在宏内部使用。正如第 8.2 节“参数处理要点”中已经解释的那样，宏使用字符串替换而不是变量作为其参数。第二种形式的主要优点是，对于函数来说，它可以稳健地处理第一种形式无法处理的极端情况。如果封闭函数没有命名参数，则在 没有任何极端情况适用时，将${ARGV}or传递${ARGN}给第一种形式相当于传递 给第二种形式。PARSE_ARGV 0

In the second form, the PARSE_ARGV option tells cmake_parse_arguments() to read the arguments directly from the set of ${ARGVx} variables, with x ranging from startIndex to (ARGC - 1). Because it reads variables directly, it does not support being used inside macros. As already explained in Section 8.2, “Argument Handling Essentials”, macros use string replacement rather than variables for its arguments. The main advantage of the second form is that for functions, it robustly handles the corner cases that the first form does not. If there are no named arguments for the enclosing function, then passing ${ARGV} or ${ARGN} to the first form is equivalent to giving PARSE_ARGV 0 to the second form when none of the corner cases apply.

这两种形式的命令的其余行为是相同的。每个都是…​Keywords在解析期间要搜索的关键字名称列表。因为它们是一个列表，所以需要用引号括起来以确保正确处理它们。定义valuelessKeywords独立的关键字参数，其作用类似于布尔开关。关键字存在意味着一回事，不存在则意味着另一回事。singleValueKeywords使用时，每个都需要在关键字后添加一个附加参数，而在multiValueKeywords使用关键字后则需要零个或多个附加参数。虽然不是必需的，但普遍的惯例是关键字全部大写，如果需要，单词之间用下划线分隔。请注意，关键字不应太长，否则使用起来很麻烦。

The rest of the behavior of the two forms of the command is the same. Each of the …​Keywords is a list of keyword names to search for during parsing. Because they are a list, they need to be surrounded by quotes to ensure they are handled correctly. The valuelessKeywords define standalone keyword arguments which act like boolean switches. The keyword being present means one thing, its absence another. The singleValueKeywords each require exactly one additional argument after the keyword when they are used, whereas multiValueKeywords require zero or more additional arguments after the keyword. While not required, the prevailing convention is for keywords to be all uppercase, with words separated by underscores if required. Note that keywords should not be too long or they can be cumbersome to use.

返回时cmake_parse_arguments()，可以定义变量，其名称由指定的prefix、下划线和与其关联的关键字的名称组成。例如，如果前缀为ARG，则与名为 的关键字对应的变量FOO将为ARG_FOO。对于每个，如果关键字存在或不存在，valuelessKeywords则将使用该值定义相应的变量。对于每个和，仅当该关键字存在并且在关键字后提供了值时才会定义相应的变量。一个示例最好地说明了如何定义和处理三种不同的关键字类型：TRUEFALSEsingleValueKeywordsmultiValueKeywords

When cmake_parse_arguments() returns, variables may be defined whose names consist of the specified prefix, an underscore and the name of the keyword they are associated with. For example, with a prefix of ARG, the variable corresponding to a keyword named FOO would be ARG_FOO. For each of the valuelessKeywords, the corresponding variable will be defined with the value TRUE if the keyword is present or FALSE if it is not. For each of the singleValueKeywords and multiValueKeywords, the corresponding variable will only be defined if that keyword is present and a value is provided after the keyword. An example best illustrates how the three different keyword types are defined and handled:

function(func)
    # Define the supported set of keywords
    set(prefix       ARG)
    set(noValues     ENABLE_NET COOL_STUFF)
    set(singleValues TARGET)
    set(multiValues  SOURCES IMAGES)

    # Process the arguments passed in
    include(CMakeParseArguments)
    cmake_parse_arguments(
        ${prefix}
        "${noValues}" "${singleValues}" "${multiValues}"
        ${ARGN}
    )

    # Log details for each supported keyword
    message("Option summary:")
    foreach(arg IN LISTS noValues)
        if(${prefix}_${arg})
            message("  ${arg} enabled")
        else()
            message("  ${arg} disabled")
        endif()
    endforeach()
    foreach(arg IN LISTS singleValues multiValues)
        # Single argument values will print as a string
        # Multiple argument values will print as a list
        message("  ${arg} = ${${prefix}_${arg}}")
    endforeach()
endfunction()

# Examples of calling with different combinations
# of keyword arguments
func(SOURCES foo.cpp bar.cpp
     TARGET MyApp
     ENABLE_NET
)
func(COOL_STUFF
     TARGET dummy
     IMAGES here.png there.png gone.png
)